Re: API documentation requirements for next releases

[Owen Taylor <otaylor redhat com>]

On Fri, 2005-12-02 at 10:33 -0500, JP Rosevear wrote:
> On Wed, 2005-11-30 at 19:03 -0600, Federico Mena Quintero wrote:
> > Hi,
> > 
> > Some time ago we discussed adding a requirement for new APIs that enter
> > the core platform [1]:  those modules which add new APIs must provide
> > documentation for those APIs.  Thanks to Murray for bringing it up, and
> > for resurrecting the discussion.
> > 
> > The release team has decided that we'll try this plan for the 2.14
> > release.  If it works out well, we'll use it for subsequent releases as
> > well.  You can see the details here:
> > 
> > 	http://live.gnome.org/ReleasePlanning/NewApiDocs
> > 
> > Summary:
> > 
> > For modules in the core platform [2], we'll require that new APIs and
> > other public interfaces have documentation.  This includes C functions,
> > configuration files, GConf keys, and anything that is not internal only.
> > 
> >      1. Document any new public interfaces since the last stable version
> >         of the module (e.g. the jump from 2.12.x to 2.14.0). You can do
> >         this with gtk-doc.
> >      2. Mark any newly deprecated interfaces as such.
> >      3. Any new module proposed for the platform must be fully
> >         documented. 
> 
> Is there a deadline for when this has to be done by?  Getting to the
> hard freeze and then realizing, "oops not done, but people now depend on
> the API" would be a bad thing.

Of course, by far the best way for a library maintainer to implement the
policy is to simply not take or apply patches without docs.

(I'm assuming that the "complete docs" above means "complete
function-by-function docs" and doesn't include the other parts that
really make docs complete like intro material and tutorials.)

Regards,
						Owen