Re: Ideas about improving gtk-doc

[Brian Cameron <Brian Cameron Sun COM>]

Okay, I wanted to restate the proposal of how to improve gtk-doc, taking
into account the various comments that have been made.

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

The descriptions of the data are found either in the source file near
the interface or in the .sgml files that are 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:

---

I'd like to recommend the following changes:

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.  The version information should be optional so gtk-doc still works
   with comments that do not include this bit of information.

2. Highlight change to data structures and enumerations:

   This could be managed by adding Since and Deprecated tags to the
   structure description as follows:

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

   Note that we also added a "Type: <string>" argument so that the datatype
   for each element can be identified.  This is optional and should really only
   be used when commenting an element that has been removed from a structure.
   The datatype should be figured out from the code directly for elements that
   are still in the data structure.  The "Type" argument is not needed for
   enumerations since they are all of the same data type.

   In the generated gtk-docs, additional text highlighting changes would
   display 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

3. Add a keyword "Stability" which will be used much like "Since" and "Deprecated".
   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 and should not be
               relied upon.
    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.  Over time it might be desirable to add more
   stability levels to describe interfaces in more level of detail, so it would
   be nice if this feature were implemented in a way that makes it easy to
   add additional stability levels.  Alternatively, gtk-doc could simply allow
   any string to be used as the stability level, so that each project can use
   whatever keywords make the most sense for that project.

   There was some question about whether this additional information would be
   useful, but I think that the discussion on the desktop-devel list highlights
   that being able to classify interfaces is something that is generally
   desired.

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.
   Files and environment variables are different than other interfaces in the
   sense that these aren't declared like a macro, enumeration or function.
   Therefore, users could include documentation comments for these two new
   types either next to a "#define" which is used to specify the FILE or
   ENVVAR or above a function that makes use of them.

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.  This would be much like the current index
   of deprecated symbols except that it would contain details about files,
   and environment variables.  It would also clearly state which version each
   symbol was deprecated.  Here's a link to an example of the page that gtk-doc
   currently can generate:

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

Damon suggests that the above changes would not be too hard to implement.
Would someone who is familiar with the gtk-doc logic be willing to make
these changes?  If not, I would appreciate it if someone could highlight
what code changes will be necessary to implement the logic so I can go
ahead and do the work.  I'm not familiar with gtk-doc's logic, so an
overview of how to go about making these sorts of changes would be
useful.

--

Brian