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

[Damon Chaplin <damon karuna uklinux net>]

On Wed, 2005-02-02 at 20:41, Brian Cameron wrote:

> > I've also just committed Stefan's patch to support adding the section
> > documentation in the source code, so we could support @stability: there
> > as well:
> >   http://bugzilla.gnome.org/show_bug.cgi?id=165963
> 
> Okay, I tried adding a comment block like this to gdkdraw.c at the top, just
> after the LGPL notice.
> 
> /*
>   * SECTION:gdktestme
>   * @summary: Display information about a testme
>   * @see: #GtkDialog
>   */
> 
> But I don't see any change in the output.  I was going to add the @stability
> option, but I'd like to see the changes in the output first.  I suspect I
> just don't know how to use this feature.
> 
> Also, if you have the SECTION stuff defined in the tmpl files and in the
> source code, which one wins?


I've just added this to gdk-pixbuf.c and it worked OK:

/**
 * SECTION:initialization_versions
 * @title: Initializing Versions Section Title
 * @short_description: a one-line description of the section.
 * @see_also: some pointers to other relevant information. This can be a
 *            paragraph.
 *
 * This is the main description of the initialization versions section.
 *
 * Multiple paragraphs can be used here, separated by blank lines.
 **/


The part after "SECTION:" needs to match the corresponding <FILE>
setting in the sections.txt file.

Inline documentation overrides tmpl files, though it does warn you when
this happens.


> > We also need to update the gtk-doc.make file to pass any required
> > "--default-stability-level=LVL" flag.
> 
> I'm happy to do this.  I took a look at the gtk-doc.make file, but am unsure
> exactly how to make the change.  How should gtk-doc.make be informed that the
> user has a defined stability level?  Would they define an environment variable
> like STABILITY_LEVEL or something?
> 
> Also, it might be nice if the gtk-doc.make file didn't have to deal with
> conditionally calling gtkdoc-mkdb with the --stability_level option.  Should
> we patch gtkdoc-mkdb.in to accept the value "Undefined" which will work the
> same way as if you didn't specify --stability_level at all?  Or does putting
> a conditional in the gtk-doc.make file make more sense?

Actually it works already. All I had to do was add the stability option
to MKDB_OPTIONS in the Makefile.am:

MKDB_OPTIONS=--main-sgml-file=$(DOC_MAIN_SGML_FILE) --sgml-mode
--source-dir=../../../contrib/gdk-pixbuf-xlib --output-format=xml
--default-stability=Stable

Damon