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

[Brian Cameron <Brian Cameron Sun COM>]

Peter:

> > However, I worry that simply making the default "Stable" and not
> > printing out any output for the default will discourage its use and
> > undermine its usefulness.  Can't we think of an approach that
> > makes the documentation a bit easier without undermining the feature?
>
>
> 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.

The point of defining stability levels for interfaces is so that
developers can have a more clear understanding of how stable each
interface is, and which interfaces they can depend upon.  Such
stability levels would become meaningless if they appear,
disappear, or change from release-to-release accidently.

Specifying the default stability level on the command line could
work, but we should be careful not to implement features that
will undermine the purpose of defining stability levels in the
first place, or make it too easy to mislabel interfaces.

I think I'm only suggesting that we think about this a bit and
make sure that we find an approach that makes things reasonable
from an ease-of-use perspective and also a perspective that
makes defining stability levels useful.

Brian