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 _______________________________________________ gtk-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtk-doc-list
