Re: API documentation requirements for next releases
- From: Daniel Veillard <veillard redhat com>
- To: Rodrigo Moya <rodrigo gnome-db org>
- Cc: Federico Mena Quintero <federico ximian com>, desktop-announce-list gnome org, gnome-hackers gnome org, GNOME Desktop <desktop-devel-list gnome org>
- Subject: Re: API documentation requirements for next releases
- Date: Thu, 1 Dec 2005 07:40:06 -0500
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/
_______________________________________________
gnome-hackers mailing list
gnome-hackers gnome org
http://mail.gnome.org/mailman/listinfo/gnome-hackers
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]