GNOME.org
 

[babl] docs: improve the generated reference

commit 51ff8e26f48c294ea2fdd486bbbd504290fb064b
Author: Øyvind Kolås <pippin gimp org>
Date:   Mon Jul 22 14:39:52 2019 +0200

    docs: improve the generated reference

 babl/babl-class.h      |   1 +
 babl/babl-core.c       |   1 +
 babl/babl-format.c     |  19 ++++++---
 babl/babl-internal.c   |  14 +++++++
 babl/babl-internal.h   |   5 +++
 babl/babl-model.c      |  12 ++++--
 babl/babl-space.h      |   2 +
 babl/babl-type.c       |  11 ++++-
 babl/base/type-float.c |   1 +
 babl/base/type-half.c  |   1 +
 babl/base/type-u8.c    |   3 ++
 docs/babl.css          |   8 +++-
 tools/babl-html-dump.c | 111 ++++++++++++++++++++++++++-----------------------
 13 files changed, 126 insertions(+), 63 deletions(-)
---
diff --git a/babl/babl-class.h b/babl/babl-class.h
index a1efa9d..ceada22 100644
--- a/babl/babl-class.h
+++ b/babl/babl-class.h
@@ -50,6 +50,7 @@ typedef struct
                               ones */
   void          *creator;
   char          *name;    /*< the name this type exists under         */
+  const char    *doc;     /*< the name this type exists under */
 } BablInstance;
 
 
diff --git a/babl/babl-core.c b/babl/babl-core.c
index c551cb9..d78b5e5 100644
--- a/babl/babl-core.c
+++ b/babl/babl-core.c
@@ -93,6 +93,7 @@ babl_core_init (void)
     "double",
     "id", BABL_DOUBLE,
     "bits", 64,
+    "doc", "IEEE 754 double precision.",
     NULL);
 
   babl_component_new (
diff --git a/babl/babl-format.c b/babl/babl-format.c
index accc15a..20617d2 100644
--- a/babl/babl-format.c
+++ b/babl/babl-format.c
@@ -52,7 +52,8 @@ format_new (const char      *name,
             const Babl      *space,
             BablComponent  **component,
             BablSampling   **sampling,
-            const BablType **type)
+            const BablType **type,
+            const char      *doc)
 {
   Babl *babl;
 
@@ -128,7 +129,7 @@ format_new (const char      *name,
 
   babl->format.space = (void*)space;
   babl->format.encoding = NULL;
-
+  babl->instance.doc = doc;
   return babl;
 }
 
@@ -149,7 +150,7 @@ format_new_from_format_with_space (const Babl *format,
                     format->format.planar, format->format.components,
                     (void*)babl_remodel_with_space (BABL(format->format.model), space),
                     space,
-                    format->format.component, format->format.sampling, (void*)format->format.type);
+                    format->format.component, format->format.sampling, (void*)format->format.type, NULL);
 
   ret->format.encoding = babl_get_name(format);
   babl_db_insert (db, (void*)ret);
@@ -285,7 +286,7 @@ babl_format_n (const Babl *btype,
                      id,
                      planar, components, model,
                      babl_space("sRGB"),
-                     component, sampling, type);
+                     component, sampling, type, NULL);
 
   babl_format_set_is_format_n (babl);
 
@@ -343,7 +344,8 @@ babl_format_new (const void *first_arg,
   int            planar     = 0;
   int            components = 0;
   BablModel     *model      = NULL;
-  const Babl    * space     = babl_space ("sRGB");
+  const Babl    *space      = babl_space ("sRGB");
+  const char    *doc        = NULL;
   BablComponent *component [BABL_MAX_COMPONENTS];
   BablSampling  *sampling  [BABL_MAX_COMPONENTS];
   const BablType*type      [BABL_MAX_COMPONENTS];
@@ -368,6 +370,11 @@ babl_format_new (const void *first_arg,
           name = babl_strdup (va_arg (varg, char *));
         }
 
+      else if (!strcmp (arg, "doc"))
+        {
+          doc = babl_strdup (va_arg (varg, const char *));
+        }
+
       else if (!strcmp (arg, "packed"))
         {
           planar = 0;
@@ -506,7 +513,7 @@ babl_format_new (const void *first_arg,
   babl = format_new ((void*)name,
                      id,
                      planar, components, model, space,
-                     component, sampling, type);
+                     component, sampling, type, doc);
 
   babl_db_insert (db, babl);
   babl_free (name);
diff --git a/babl/babl-internal.c b/babl/babl-internal.c
index 5609720..b0c1831 100644
--- a/babl/babl-internal.c
+++ b/babl/babl-internal.c
@@ -113,3 +113,17 @@ babl_get_name (const Babl *babl)
   babl_assert (BABL_IS_BABL (babl));
   return babl->instance.name;
 }
+
+const char *
+babl_get_doc (const Babl *babl)
+{
+  babl_assert (BABL_IS_BABL (babl));
+  return babl->instance.doc;
+}
+
+void babl_doc (const Babl     *babl,
+               const char     *doc)
+{
+  babl_assert (BABL_IS_BABL (babl));
+  ((Babl*)babl)->instance.doc = doc;
+}
diff --git a/babl/babl-internal.h b/babl/babl-internal.h
index 95ca661..c476827 100644
--- a/babl/babl-internal.h
+++ b/babl/babl-internal.h
@@ -100,6 +100,11 @@ double   babl_model_is_symmetric        (const Babl     *babl);
 void     babl_die                       (void);
 int      babl_sanity                    (void);
 
+void     babl_doc                       (const Babl     *babl,
+                                         const char     *doc);
+
+const char * babl_get_doc (const Babl *babl);
+
 void     babl_core_init                 (void);
 const Babl *babl_format_with_model_as_type (const Babl     *model,
                                          const Babl     *type);
diff --git a/babl/babl-model.c b/babl/babl-model.c
index 142734c..727e6d6 100644
--- a/babl/babl-model.c
+++ b/babl/babl-model.c
@@ -57,7 +57,8 @@ model_new (const char     *name,
            int             id,
            int             components,
            BablComponent **component,
-           BablModelFlag   flags)
+           BablModelFlag   flags,
+           const char     *doc)
 {
   Babl *babl;
 
@@ -70,6 +71,7 @@ model_new (const char     *name,
 
   babl->class_type       = BABL_MODEL;
   babl->instance.id      = id;
+  babl->instance.doc     = doc;
   babl->model.components = components;
   babl->model.space      = space;
   babl->model.data       = NULL;
@@ -117,6 +119,7 @@ babl_model_new (void *first_argument,
   const char    *arg           = first_argument;
   const char    *assigned_name = NULL;
   char          *name          = NULL;
+  const char    *doc           = NULL;
   const Babl    *space         = babl_space ("sRGB");
   BablComponent *component [BABL_MAX_COMPONENTS];
   BablModelFlag  flags         = 0;
@@ -130,7 +133,10 @@ babl_model_new (void *first_argument,
         {
           id = va_arg (varg, int);
         }
-
+      else if (!strcmp (arg, "doc"))
+        {
+          doc = va_arg (varg, const char *);
+        }
       else if (!strcmp (arg, "name"))
         {
           assigned_name = va_arg (varg, char *);
@@ -257,7 +263,7 @@ babl_model_new (void *first_argument,
 
   if (! babl)
     {
-      babl = model_new (name, space, id, components, component, flags);
+      babl = model_new (name, space, id, components, component, flags, doc);
       babl_db_insert (db, babl);
       construct_double_format (babl);
     }
diff --git a/babl/babl-space.h b/babl/babl-space.h
index 4c97cdb..7a905e2 100644
--- a/babl/babl-space.h
+++ b/babl/babl-space.h
@@ -41,6 +41,7 @@ typedef struct
 #endif
 } BablCMYK;
 
+#if 0  // draft datastructures for spectral spaces
 typedef struct _BablSpectrumType BablSpectrumType;
 
 struct _BablSpectrumType {
@@ -86,6 +87,7 @@ typedef struct
   float  stochastic_diffusion0;
   float  stochastic_diffusion1;
 } BablProcessSpace;
+#endif
 
 typedef struct
 {
diff --git a/babl/babl-type.c b/babl/babl-type.c
index 12a3e02..c079828 100644
--- a/babl/babl-type.c
+++ b/babl/babl-type.c
@@ -38,7 +38,8 @@ babl_type_destroy (void *data)
 static Babl *
 type_new (const char *name,
           int         id,
-          int         bits)
+          int         bits,
+          const char *doc)
 {
   Babl *babl;
 
@@ -50,6 +51,7 @@ type_new (const char *name,
   babl->instance.name  = (void *) ((char *) babl + sizeof (BablType));
   babl->class_type     = BABL_TYPE;
   babl->instance.id    = id;
+  babl->instance.doc   = doc;
   strcpy (babl->instance.name, name);
   babl->type.bits      = bits;
   babl->type.from_list = NULL;
@@ -77,6 +79,7 @@ babl_type_new (void *first_arg,
   int         bits       = 0;
   const char *name = first_arg;
   const char *arg;
+  const char *doc = NULL;
 
   va_start (varg, first_arg);
 
@@ -104,6 +107,10 @@ babl_type_new (void *first_arg,
         {
           (void) va_arg (varg, long);
         }
+      else if (!strcmp (arg, "doc"))
+        {
+          doc = va_arg (varg, const char*);
+        }
       else if (!strcmp (arg, "max"))
         {
           (void) va_arg (varg, long);
@@ -150,7 +157,7 @@ babl_type_new (void *first_arg,
       return babl;
     }
 
-  babl = type_new (name, id, bits);
+  babl = type_new (name, id, bits, doc);
 
   /* Since there is not an already registered instance by the required
    * id/name, inserting newly created class into database.
diff --git a/babl/base/type-float.c b/babl/base/type-float.c
index ee05c37..5b03b3f 100644
--- a/babl/base/type-float.c
+++ b/babl/base/type-float.c
@@ -89,6 +89,7 @@ babl_base_type_float (void)
     "float",
     "id", BABL_FLOAT,
     "bits", 32,
+    "doc", "IEEE 754 single precision",
     NULL);
 
   babl_conversion_new (
diff --git a/babl/base/type-half.c b/babl/base/type-half.c
index edb0390..862d662 100644
--- a/babl/base/type-half.c
+++ b/babl/base/type-half.c
@@ -401,6 +401,7 @@ babl_base_type_half (void)
     "half",
     "id", BABL_HALF,
     "bits", 16,
+    "doc", "IEEE 754 half precision.",
     NULL);
 
   babl_conversion_new (
diff --git a/babl/base/type-u8.c b/babl/base/type-u8.c
index 5e55e4d..d41d5e0 100644
--- a/babl/base/type-u8.c
+++ b/babl/base/type-u8.c
@@ -208,12 +208,14 @@ babl_base_type_u8 (void)
     "u8",
     "id", BABL_U8,
     "bits", 8,
+    "doc", "uint8_t, 8 bit unsigned integer, values from 0-255",
     NULL);
 
   babl_type_new (
     "u8-luma",
     "id", BABL_U8_LUMA,
     "bits", 8,
+    "doc", "8 bit unsigned integer, values from 16-235",
     NULL
   );
 
@@ -227,6 +229,7 @@ babl_base_type_u8 (void)
     "max", (long) 240,
     "min_val", -0.5,
     "max_val", 0.5,
+    "doc", "8 bit unsigned integer -0.5 to 0.5 maps to 16-240",
     NULL
   );
   babl_conversion_new (
diff --git a/docs/babl.css b/docs/babl.css
index 79e62ec..c63b7f3 100644
--- a/docs/babl.css
+++ b/docs/babl.css
@@ -60,7 +60,6 @@
       }
       div.expander_content {
         margin-left: 3em;
-        display: none;
         padding-bottom: 1em;
       }
       div.expander_content dl{
@@ -314,3 +313,10 @@
           display: none;
         }
       }
+
+.item_title {  font-weight: bold; margin-top: 1.5em; margin-bottom: 0.6em;
+}
+
+
+.item_body { 
+}
diff --git a/tools/babl-html-dump.c b/tools/babl-html-dump.c
index 079b2d7..0f294a0 100644
--- a/tools/babl-html-dump.c
+++ b/tools/babl-html-dump.c
@@ -16,7 +16,7 @@
  * <https://www.gnu.org/licenses/>.
  *
  */
-
+ 
 #include "config.h"
 #include "babl-internal.h"    /* needed for babl_log */
 
@@ -29,6 +29,9 @@ type_html (Babl *babl);
 static void 
 format_html (Babl *babl);
 
+static void 
+space_html (Babl *babl);
+
 static void 
 conversion_html (Babl *babl);
 
@@ -36,36 +39,11 @@ static int
 each_item (Babl *babl,
            void *user_data);
            
-static int 
-show_item (Babl *babl,
-           void *user_data);
-
-static int  
-hide_item (Babl *babl,
-           void *user_data);
-
-
 int
 main (void)
 {
   babl_init ();
 
-  printf ("<br/><a href='javascript:");
-  printf ("show(\"x_types\");show(\"x_models\");show(\"x_formats\");show(\"x_conversions\");");
-  babl_type_class_for_each (show_item, NULL);
-  babl_model_class_for_each (show_item, NULL);
-  babl_format_class_for_each (show_item, NULL);
-/*  babl_conversion_each (show_item, NULL);*/
-  printf ("'>+</a>");
-
-  printf ("<a href='javascript:");
-  printf ("hide(\"x_types\");hide(\"x_models\");hide(\"x_formats\");hide(\"x_conversions\");");
-  babl_type_class_for_each (hide_item, NULL);
-  babl_model_class_for_each (hide_item, NULL);
-  babl_format_class_for_each (hide_item, NULL);
-  /*babl_conversion_each (hide_item, NULL);*/
-  printf ("'>-</a>");
-
   printf ("<div class='expander'>");
   printf ("<div class='expander_title'><a style='font-size:110%%' name='Data-types' 
href='javascript:toggle_visible(\"x_types\")'>Data types</a></div><div class='expander_content' 
id='x_types'>\n");
   babl_type_class_for_each (each_item, NULL);
@@ -114,6 +92,9 @@ normalize (const char *str)
           (*s >= '0' && *s <= '9'))
         {
         }
+      else if (*s == '~')
+        {
+        }
       else
         {
           *s = '_';
@@ -124,32 +105,15 @@ normalize (const char *str)
 }
 
 
-static int
-show_item (Babl *babl,
-           void *user_data)
-{
-  printf ("show(\"x_%s\");", normalize (babl->instance.name));
-  return 0;
-}
-
-
-static int
-hide_item (Babl *babl,
-           void *user_data)
-{
-  printf ("hide(\"x_%s\");", normalize (babl->instance.name));
-  return 0;
-}
-
 static int
 each_item (Babl *babl,
            void *user_data)
 {
-  printf ("<div class='expander'>");
-  printf ("<div class='expander_title'><a href='javascript:toggle_visible(\"x_%s\")'>%s</a></div>\n",
-          normalize (babl->instance.name), babl->instance.name);
-  printf ("<div class='expander_content' id='x_%s'>\n",
-          normalize (babl->instance.name));
+  printf ("<div><div class='item_title'><a href='#%s', name='%s'>%s</a></div>\n",
+          normalize (babl->instance.name),
+          normalize (babl->instance.name),
+          babl->instance.name);
+  printf ("<div class='item_body'>");
 
 
   switch (babl->class_type)
@@ -166,6 +130,10 @@ each_item (Babl *babl,
         format_html (babl);
         break;
 
+      case BABL_SPACE:
+        space_html (babl);
+        break;
+
       case BABL_CONVERSION:
       case BABL_CONVERSION_LINEAR:
       case BABL_CONVERSION_PLANE:
@@ -182,10 +150,24 @@ each_item (Babl *babl,
   return 0;
 }
 
+static void
+model_doc (const Babl *babl)
+{
+  if (babl->instance.doc)
+    printf ("%s", babl->instance.doc);
+  else
+    {
+    }
+}
+
+
 static void
 model_html (Babl *babl)
 {
   int i;
+  printf ("<p>");
+  model_doc (babl);
+  printf ("</p>");
 
   printf ("<dl>");
   printf ("<dt>components</dt><dd><table class='nopad'>");
@@ -201,6 +183,9 @@ model_html (Babl *babl)
 static void
 type_html (Babl *babl)
 {
+  if (babl->instance.doc)
+    printf ("<p>%s</p>", babl->instance.doc);
+
   printf ("<dl><dt>bits</dt><dd>%i</dd>", babl->type.bits);
   printf ("<dt>bytes</dt><dd>%i</dd></dl>", babl->type.bits / 8);
 }
@@ -209,22 +194,46 @@ type_html (Babl *babl)
 static void
 conversion_html (Babl *babl)
 {
-  printf ("\n");
+  printf ("%s<br/>\n", babl->instance.name);
+}
+
+static void
+space_html (Babl *babl)
+{
+  printf ("%s<br/>\n", babl->instance.name);
 }
 
 static void
 format_html (Babl *babl)
 {
   int i;
+  const Babl *model = BABL (babl->format.model);
+
+  printf ("<p>");
+  if (babl->instance.doc)
+    printf ("%s", babl->instance.doc);
+  else
+    {
+      const Babl *type = BABL (babl->format.type[0]);
+      model_doc (model);
+      if (type->instance.doc)
+        printf (" %s", type->instance.doc);
+      else
+        printf (" %s", type->instance.name);
+    }
+  printf ("</p>");
 
   printf ("<dl>");
   printf ("<dt>bytes/pixel</dt><dd>%i</dd>", babl->format.bytes_per_pixel);
-  printf ("<dt>model</dt><dd>%s</dd>", BABL (babl->format.model)->instance.name);
+  printf ("<dt>model</dt><dd><a href='#%s'>%s</a></dd>",
+    normalize( BABL (babl->format.model)->instance.name),
+    BABL (babl->format.model)->instance.name);
   printf ("<dt>components</dt><dd><table class='nopad'>");
 
   for (i = 0; i < babl->format.components; i++)
     {
-      printf ("<tr><td class='type'>%s</td><td class='component'>%s</td></tr>",
+      printf ("<tr><td class='type'><a href='#%s' style='color:white''>%s</a></td><td 
class='component'>%s</td></tr>",
+              normalize(BABL (babl->format.type[i])->instance.name),
               BABL (babl->format.type[i])->instance.name,
               BABL (babl->format.component[i])->instance.name);
     }
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]