Re: Ideas about improving gtk-doc

[Damon Chaplin <damon karuna uklinux net>]

On Thu, 2004-12-02 at 21:53, Brian Cameron wrote:
> Some people might have noticed my recent discussion on the
> desktop-devel-list where I suggested some ideas about improving
> gtk-doc.  Refer here:
> 
>     http://mail.gnome.org/archives/desktop-devel-list/2004-November/msg00738.html
> 
> So you don't have to read that email, I'll restate the parts of that
> email that relate to gtk-doc.
> 
> Here at Sun, we use the GNOME documentation generated by gtk-doc for our
> ARC (Architecture Review Committee) review process.  The ARC reviews the
> documentation to ensure that interfaces are changing in ways that
> support ABI compatibility, and the like.
> 
> Unfortunately the documentation that gtk-doc generates is not complete
> from an ARC perspective, and we here at Sun have to manually dig through
> the code to generate the missing bits.  This is very time-consuming, and
> it seems like a better approach might simply be to improve the gtk-doc
> application so that more interface information is captured.
> 
> Specifically, making it possible to document the following sort of
> interface information would be very useful:
> 
> + Making it possible to document changes to data structures, enumerations,
>    etc.  It is not uncommon for new data elements to be added to a data
>    structure or for new enumerations to be added since these sorts of
>    changes do not break ABI-compatibility.  Making it possible to highlight
>    such changes in the gtk-docs would make it more clear to the end user
>    how functions should be properly used for the version of the library
>    they are using.  It would also be useful to identify when enumerations
>    and data structures were added as interfaces to the library.

Yes, documenting these changes is probably quite useful.


> + Making it possible to document file interfaces, so if the code
>    depends on data being in a certain file location (such as in
>    /usr/share), this can be made visible in the documentation.  It
>    would be especially useful to document file locations that are
>    useful for integrating into the desktop.  This way users who read
>    the documentation will know where to install files to integrate
>    with the GNOME component model, themes, etc.
> 
>    For example, libgnome could document that it makes use of
>    /usr/share/locale/locale.alias in the gnome-i18n.c file.

Yes, this would be useful too. I think some files are probably
documented within the current documentation, but it would probably be
useful to document them separately, in a systematic way.

And similarly for other things like environment variables.


> + Making is possible for gtk-doc to generate a list of deprecated
>    or removed interfaces that includes the specific release information
>    about when the interface was deprecated or removed.

Currently we mark functions as deprecated (by looking for macros like
GTK_DISABLE_DEPRECATED in headers), but we don't keep version info.

I think keeping track of removed interfaces may be awkward, as all
information about them would probably disappear from the code, and that
is where gtk-doc looks for information.


> + Making it possible to label an interface's stability level so that
>    users of the interface can know whether or not the interface is
>    "stable" and not going to break in a minor-release or whether the
>    interface is "unstable" or "private" and is therefore not guaranteed
>    to work with future versions of the library.

Do you mean on a module or function/struct/enum level, or both?
I guess that is useful too.

(We already allow things like functions/enums or individual struct
members to be marked "private", and they don't appear in the docs.)


> I'm wondering if the gtk-doc community agrees that these sorts of
> improvements to gtk-doc would be beneficial to the community and to
> the quality of the generated documentation.  If there is an interest,
> I'd be delighted to work on improving gtk-doc to do these sorts of
> additional tasks.  First, though, it would be useful to discuss how
> such improvements would best be integrated into the current tool.

I think the information would generally be useful. Unfortunately I don't
think any of the gtk-doc maintainers want to spend much time on it, so
you may have a bit of trouble getting feedback/patch reviews etc.


Also, even if you add support for documenting these things, you probably
can't rely on developers adding the documentation. Even now you need to
be aware that not all functions/enums etc. appear in the documentation,
since developers forget to add them to the *-sections.txt file.

It would probably be wise to also write your own tools to scan the
installed header files and check the differences between versions. (You
could pinch the gtk-doc scanning code to start with.)

Damon