Re: Interface Stability (was Re: xxx-undocumented.txt)

[Damon Chaplin <damon karuna uklinux net>]

On Wed, 2005-01-26 at 10:42, Stefan Kost wrote:
> hi hi,
> 
> Peter Williams wrote:
> > 
> > Maybe let the developer be able to specify the default stability: via a
> > command-line flag, or at the top of each source file, etc. Such as:
> > 
> > 	gtk$ gtkdoc-mkdb --default-stability=Stable ...
> > 
> > 	libwnck$ gtkdoc-mkdb --default-stability=Private
> > 
> > And if the developer doesn't bother, go with Undefined.
> 
> that sounds good to me. Fits with the gtkdoc concept. And if the default does
> not fit entries than one still can put them in the file. Would be nice if one
> could say that e.g. everything in gtk+-2.5 that wasn't there in 2.4 is
> considered unstable ...
> 
> As an extension it would be thinkable to specify the default stababillity in the
> section comment as well (when that is implemented).
> 
> /**
>  * SECTION:gtkaboutdialog
>  * @summary: Display information about an application
>  * @see: #GtkDialog
>  * @stabillity: Stable
>  *
>  * The #GtkAboutDialog offers a simple way to display information
>  * about a program like its logo, name, copyright, website and license.
>  */
> 
> Still parts can overide this (e.g. a new methods that needs testing).


I think both of these ideas are fine. (I nearly suggested a
--default-stability flag before.)

I really don't want to force people to add "@stabillity:" everywhere.

Damon