Re: Ideas about improving gtk-doc

[Matthias Clasen <mclasen redhat com>]

On Thu, 2004-12-09 at 17:51 -0600, Brian Cameron wrote:
> 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):

You can document things in the templates, but generally we prefer to 
document things inline in the sources now (at least for glib, pango and
gtk+). Only the short and long descriptions still *have* to be provided
in the templates.

> ---
> 
> <!-- ##### 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.

Do you win much by providing that information ? If an application is
supposed to be working with, say 2.2, it has to be compiled against 2.2
anyway, therefore the developer will likely have 2.2 (and thus also the
2.2 docs) installed somewhere anyway.

> 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.

I wouldn't mix abi checking with documentation. I can see us adding
struct size checks for important public derivable classes to the gtk abi
checking, but there is no way to make this kind of abi checking
completely waterproof. 

>     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

We can't remove public APIs anyway, only deprecate them. And if they are
not public, they shouldn't show up in the docs.

> 
>     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.

See above. Instead of figuring out ways to document abi breakage, we
should just avoid breaking abi.

> 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.

I'm not sure this is really worth adding to the docs in any formal way.
You can always add information about this informally. Obsolete doesn't
seem to add anything beyond Deprecated, and private apis should simply
be left out of the docs.
For unstable, one could think about utilising the defines we use in some
places for apis which are considered less stable, e.g.
GDK_PIXBUF_ENABLE_BACKEND or PANGO_ENABLE_BACKEND.

> 
> 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.

We have documented them in a dedicated section in the gtk+ and glib api
docs. Would you win much by moving these docs to the templates ? It
might be a win to be able to document them in the source next to the
functions using them, but for that you need to invent a nonconflicting
hash key syntax, so that you can stuff them in the global symbol hash.

> 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.

Like http://developer.gnome.org/doc/API/2.0/gtk/ix02.html ?


Regards, Matthias