Re: Demanding API documentation

[Brian Cameron <Brian Cameron Sun COM>]

Murray:

>>> Would any platform maintainers object to the release-team demanding that
>>> a) Any new API (functions, signals, properties, etc) in an existing

I would word this "Any new public interfaces" rather than API since
interfaces such as file installation locations that are intended for
public editing (such as the gdm.conf file in GDM) should also be
documented.  Such non-API interfaces can be documented in gtk-doc,
like the .gtkrc file for the GTK+ library.  I don't think it needs to
be a requirement that all public interfaces need to be documented via
gtk-doc, just that they are clearly documented somewhere (Docbook,
or module README, or wherever).

>>> Platform module should have at least some documentation, usually with
>>> gtk-doc. Non-public API should be clearly marked, and the documentation
>>> should say when new API was introduced (e.g. "since GTK+ 2.6").

Also, deprecated symbols should be documented properly.

One reasonable way of "marking non-public API" would be to simply
omit such functions from the documentation.  Then GNOME could have
a clear policy like "interfaces intended for ISV usage are documented
interfaces in platform modules, unless otherwise marked."  Actually
this is pretty much what GNOME already does, there just isn't a clear
policy worded anywhere yet.

In preparation for GNOME 3.0, the Release Team might also want to set
documentation expectations for when ABI breaks.  For example, the glib
and GTK+ documentation includes examples that highlight how to migrate
code from 1.x to 2.x.  It might be reasonable to expect this degree
of quality from all GNOME platform modules.

> > How will this work in practise ? Will the release team check all new
> > apis for conformance to this rule at the beginning of the api freeze
> > period ?  
>
> Good question. Maybe we could have some kind of period between API
> freeze and a must-be-documented time. Or maybe we could demand that API
> is documented when it's first released in a tarball.
>
> We couldn't depend on the release time to find undocumented API, but we
> could allow the release team to complain if they discover it, and make
> it clear that documentation is seriously expected. The release-team
> doesn't usually have to tell people what to do, but we can make it
> clearer what everybody wants.

I think that it is reasonable for the Release Team to highlight
expectations, and expect the maintainers to follow them.  If issues
are discovered they can be treated as bugs.

If we wanted to check API's for more rigorous conformance, this could
be done for libraries like glib and GTK+ by comparing the *.symbols
file (like gtk/gtk.symbols) from one version to the next and checking
to make sure that any differences are in the gtk-docs.  This probably
wouldn't be too time-consuming, since the number of added/deprecated
interfaces from release-to-release is typically not great.

These *.symbols files are an artifact of the abicheck.sh script
used by glib and GTK+ to verify that ABI breakage does not occur
from release-to-release.  It might be worthwhile for the Release
Team to encourage all platform module maintainers to start using
similar abicheck.sh testing.  Perhaps it doesn't need to be made
a requirement, but a "best practice" that is encouraged.  It
could be made a requirement, perhaps, for new modules moving into
the Platform.

Brian