Re: API documentation requirements for next releases

[Elijah Newren <newren gmail com>]

On 11/30/05, Federico Mena Quintero <federico ximian com> 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:

Thanks for sending this out Federico.  One minor nitpick is that I
would personally prefer wording that doesn't connotate the release
team deciding and imposing stuff but rather that reflects it being
something the community agreed to (or didn't care enough to object
to...).  Do others feel the same way?

>         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.

This doesn't quite look like Murray's proposal to me[1] --
configuration files, GConf keys, etc. didn't seem to be covered by my
understanding.  Not sure how best to handle that.  Thoughts?

Cheers,
Elijah

[1] , "a) Any new API (functions, signals, properties, etc) in an
existing Platform module should have at least some documentation,
usually with gtk-doc. Non-public API should be clearly marked, and the
documentation should say when new API was introduced (e.g. "since GTK+
2.6").", from http://mail.gnome.org/archives/desktop-devel-list/2005-August/msg00003.html