Re: API documentation requirements for next releases

[Daniel Veillard <veillard redhat com>]

On Thu, Dec 01, 2005 at 01:18:00PM +0100, Rodrigo Moya wrote:
> 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?

  I will have to change my tools, but yes.

Daniel

-- 
Daniel Veillard      | Red Hat http://redhat.com/
veillard redhat com  | libxml GNOME XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/