Ideas about improving gtk-doc

[Brian Cameron <Brian Cameron Sun COM>]

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.

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

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

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

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.

--

Brian