Re: API documentation requirements for next releases

[Rodrigo Moya <rodrigo gnome-db org>]

On Thu, 2005-12-01 at 06:58 -0500, Daniel Veillard wrote:
> On Wed, Nov 30, 2005 at 07:03:50PM -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. 
> 
>   That comes out of the blue for me. I'm not adverse to this, but as one
> of the affected modules maintainers I would have loved to heard from it
> before, especially as I don't use gtk-doc (I tried for years and finally
> wrote my own stuff upon which I firmly depends on at this point) and I will
> need to customize my tools.
>   Don't get me wrong, I think it's a good idea, but the process to make
> sure it works for everybdy sounds really broken !
> 
whatever documentation system you use, you can still document the
undocumented things and force documentation for all new API to be
written, right?
-- 
Rodrigo Moya <rodrigo gnome-db org>