Re: Ideas about improving gtk-doc

[Brian Cameron <Brian Cameron Sun COM>]

Damon:

> > 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. 
>
> I think the "Deprecated:" tag with the descriptive text is currently
> optional. gtk-doc also looks for macros like GTK_DISABLE_DEPRECATED in
> the header files, and marks any declarations inside that as deprecated.
>
> So for your change we'd also have to add "Deprecated:" tags to a lot of
> deprecated symbols. That isn't a big problem though.

Yes, I realize that adding this feature would require adding more comments to the
code to make sure all deprecated symbols are documented.  However, I think this
would improve the quality of the documentation and make it easier to see what
changes have taken place from release-to-release.


> > 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.
>
>
> My only worry here is struct fields and enumeration values that have
> been removed. We may still have the description of the field or enum
> value, but since it isn't in the C file anymore we don't know what its
> type or integer value was. Does that matter for the docs?
> If it does, maybe it should be left in the source code but commented
> out.

Yes, I think that keeping track of the type information would be useful.  This could
be done by leaving the removed code in a comment, or by including the type information
in the text for structures, perhaps like this:

  @GDK_FOO: Since 2.6: Type gint: foreign window (see gdk_window_foreign_new())

Obviously if we add extra fields like Since and Type to the description like this,
then they should be treated as optional.  gtk-doc should still generate good docs
if the Since and/or Type information is not included in the description.


> > 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 we need "Obsolete" when we can already mark the interface
> as deprecated. Is there any difference?

No, there is no difference in Obsolete and Deprecated.  It can be removed from the
suggestion.


> > 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.
>
> I would like to see these. I agree with you that we are doing a really
> bad job at documenting these types of things at present.

I think the gtk-doc tool is a great free software tool that generates very
useful documentation.  I'm not trying to suggest that it does a bad job in any
way.  Instead, I'm just trying to suggest ways it could be more complete and
cover more documentation issues than it currently does.


> > 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.
>
> Do you mean by using things like the "Since:" and "Deprecated:" tags?
> That should be fairly easy.

Yes.  Currently the gtk-docs generate a page that highlights added and removed
symbols.  The gtk-docs do highlight what version a symbol was added, but lumps
all the deprecated symbols together.

I think it would be more useful if this was enhanced so that version information
was included for deprecated symbols and if it covered interfaces like
enumerations, data structures, environment variables and files as well as symbols.

Then the gtk-docs would become a nice reference so that a user could quickly
see what interface changes have occurred with each release in addition to being
a useful developer tool for finding out what the interfaces do.

> Overall I'm happy with the proposed changes. They don't look too hard to
> implement.

Thanks.  Tomorrow, I will update my original proposal to reflect the comments
that people have made.  Once I get that cleaned up, we can review it once again
to verify that we like the proposal.

--

Brian