Re: Ideas about improving gtk-doc

[Brian Cameron <Brian Cameron Sun COM>]

Damon:

Thanks for your comments.  I find it encouraging that you think the
sorts of improvements I suggest would be useful.

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

On the other hand, having a mechanism within gtk-doc to allow modules
to keep track of deprecated interfaces seems like it would be a useful
feature, at least for those modules that wanted to ensure that the
code contains comments to document them.  I'd be interested in
suggestions that would make keeping such documentation less awkward.
Perhaps gtk-doc could look for a special file where such information
could be maintained rather than storing such information in the
source code (since, as you say, deprecated functions are often
removed from the code at some point).

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

Yes, I mean that it would be useful to specify the stability level for
any interface (file/function/struct/enum/environment-variable).
Obviously not all modules would care to make use of such a feature,
but for modules that want to clearly highlight stability in the
docs, this would be useful.

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

Right, but what I'm suggesting is being able to specify the stability
level for public functions.  This would allow module maintainers to
let users know how stable a public function is.  Is it a stable
interface that the user can expect to work when there is a new
release of the library, or is it an unstable function that may
break with the next release or in the near future.

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

I'm happy to do the work, or work with people who might also be
interested in making such enhancements.  I hope that there is at
least enough interest to review patches so that changes can be
put back into the gtk-doc module.  Does gtk-doc need a new
maintainer?  If so, I would be happy to help.

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

I understand.  Since I need to provide such documentation as a part
of our internal Sun ARC review process, I would be happy to work with
module maintainers to ensure that these new features are used as much
as possible and that overall coverage improves.

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

Yes, we do this as well here at Sun to try and ensure that things like
ABI compatibility are in order.  My interest in improving the doc tools
and the community docs is that we have to provide this sort of
additional detail when we go through our internal Sun ARC process.
Since this sort of documentation seems to be generally useful, my
hope is that module maintainers will be agreeable to make use of
such features to have more complete developer docs.  The bonus for
me is that if this can be done, I will eliminate a lot of tedious
internal documentation I have to do here at Sun.  Instead I can do
a lot of tedious work with module maintainers, but at least there
will be the benefit of improving the public docs.

--

Brian