Re: API documentation requirements for next releases

[Daniel Veillard <veillard redhat com>]

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 !

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/