Re: Ideas about improving gtk-doc

[Brian Cameron <Brian Cameron Sun COM>]

Stefan:

> > That sounds great.  I would be delighted to work with a student to
> > implement
> > features to improve gtk-doc.  In my last email I think I pretty clearly
> > specified the high-level features that would be useful to add.  Could you
> > be more specific about what additional information you need in a TODO file?
>
> I don't yet have one here. But before thying to motivate (convince) one to do
> it, one needs enough ideas, so that it is enough for a diploma work.
> With a TODO file I mean having a list of wanted features along with some note on
> how it should be implemented (kind of use cases), e.g. how would one like to
> document an information and how should it appear in the output.
> If the maintainer(s) agree on the entries in such a file, one can spend time on
> implementing it without fearing that the change is not wanted.

That's a fair point.  I don't know much about the internals of gtk-doc myself,
but I've spent the past few days looking over the code and think I understand how
it is working.  I've put together the following information and some suggestions
about how we could achieve better coverage for change in the gtk-docs.  I would
definately appreciate it if someone who understands gtk-doc better than myself
could let me know if these approaches seem reasonable, or if adding these
features would require more dramatic change to the way gtk-doc works.

Looking into the OutputDeclaration method in gtkdoc-mktmpl, I notice that the
following special keywords are supported:

Type FUNCTION and USER_FUNCTION
   Returns (if function is not void)
   Deprecated
   Since

Type MACRO
   Returns
   Deprecated
   Since

Type STRUCT
   Deprecated
   Since

Type ENUM
   Deprecated
   Since

Looking into gtkdoc-mkdb you can see how these are processed in the
methods OutputMacro, OutputTypedef, OutputStruct, OutputEnum,
OutputUnion, OutputVariable, OutputFunction, GetSignals, GetArgs,
ScanSourceFile, ReadTemplateFile.  The "Since" option is used directly
in these functions.  The "Deprecated" option is handled by the
MakeDeprecationNode method.  The "Returns" option is handled in the
ScanSourceFile by simply adding the return value to the end of the
param list, then OutputParamDescriptions deals with it.

My understanding is that the gtk-docs are built from the .sgml files
that are normally stored in the "tmpl" directory of a module.  These
files have a structure that looks like this (using gdk's code as an
example for STRUCT, ENUM, and FUNCTION):

---

<!-- ##### STRUCT GdkRectangle ##### -->
<para>
Defines the position and size of a rectangle.
</para>

@x: the x coordinate of the left edge of the rectangle.
@y: the y coordinate of the top of the rectangle.
@width: the width of the rectangle.
@height: the height of the rectangle.

<!-- ##### ENUM GdkWindowType ##### -->
<para>
Describes the kind of window.
</para>

@GDK_WINDOW_ROOT: root window; this window has no parent, covers the entire screen, and
 is created by the window system
@GDK_WINDOW_TOPLEVEL: toplevel window (used to implement #GtkWindow)
@GDK_WINDOW_CHILD: child window (used to implement e.g. #GtkButton)
@GDK_WINDOW_DIALOG: useless/deprecated compatibility type
@GDK_WINDOW_TEMP: override redirect temporary window (used to implement #GtkMenu)
@GDK_WINDOW_FOREIGN: foreign window (see gdk_window_foreign_new())

<!-- ##### FUNCTION gdk_display_get_name ##### -->
<para>

</para>

@display:
@Returns:

---

With that overview, some suggestions about how we could add the needed
functionality follow:

1. Currently the "Deprecated" tag only highlights information about
   the deprecation, such as:

   * Deprecated: Use gdk_draw_layout() instead.

   Changing this to also include information about what version the deprecation
   happened would be useful.  For example, if a function was deprecated in
   version 2.6, the tag could look like this:

   * Deprecated: 2.6: Use gdk_draw_layout() instead.

   Then the version information could be included along with the descriptive
   text.

2. Highlight change to data structures and enumerations:

   Perhaps this could be done by adding a new keyword to the list so a new element
   could be highlighted by:

   @height:Since 2.6: the height of the rectangle.
   @height:Removed 2.6: the height of the rectangle.
   @GDK_WINDOW_FOREIGN: Since 2.6: foreign window (see gdk_window_foreign_new())
   @GDK_WINDOW_FOREIGN: Removed 2.6: foreign window (see gdk_window_foreign_new())

   The scripts for checking structures should be smart enough to verify ABI
   compatibility.  In other words, ABI is only not broken if elements in data
   structures are added to the end of the structure.  If enumeration values
   or data structure elements are removed, or if elements in data structures
   are added in anywhere but the end, this should be highlighted as an ABI
   breakage.

   In the generated gtk-docs, additional text highlighting changes would look
   something like this:

   enum GtkFooEnum
   typedef enum
   {
      GTK_FOO_VALUE_1
      GTK_FOO_VALUE_3  (Added 2.6)
   } GtkFooEnum

   GTK_FOO_VALUE_2  Removed 2.4

   Values added to the end of a structure sould be displayed like this:

   GtkFooStruct
   typedef struct {
      gint val1
      gint val2
      gint val3  (Added 2.6)
   }

   When a structure changes in a way other than an addition to the last element, it
   should be be displayed like this:

   GtkFooStruct
   typedef struct {
      gint val1
      gint val3 (Added 2.6)
   }

   Stucture 2.6 and earlier:

   GtkFooStruct
   typedef struct {
      gint val1
      gint val2
      gint val3  (Added 2.6)
   }

   If a structure changes in a way that breaks ABI compatibility, it would be useful
   if functions that make use of the structure are highlighted as being affected by
   the breakage.

3. Add a keyword "Stability" which will be used much like "Since", "Deprecated", etc.
   Valid values would be:

   Stable   - the interface is not going to change until the next major release
              (2.0 to 3.0 for example).  It will not change in a minor release
              (like 2.2 to 2.6)
   Unstable - the interface may change in a minor release.
   Obsolete - the interface exists, but should not be used since it is obsolete,
              typically when the function has been deprecated.
   Private  - the interface exists only for private use and should not be used
              for general consumption.  An example would be a gdk function that
              can be used by gtk, but should not be used by any other library.

   Such stability levels would be displayed along with the function information
   in the generated gtk-docs.

4. Add two new types, FILE and ENVVAR, for documenting files and environment
   variables.  They would also support the "Since" and "Deprecated" tags.
   They would work much in the same way as ENUM or STRUCT except that they
   would document a file or environment variable rather than a macro.

5. It would be useful if gtk-docs generated an additional page that highlights
   all changes that are found in the gtk-docs.  This page would highlight all
   interfaces (functions, structures, enumerations, files, environment variables)
   deprecated, added, or changed in all previous releases.  This would serve as a
   reference page to anyone who is interested in seeing what interfaces have
   changed from release-to-release.

--

Brian