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

[Brian Cameron <Brian Cameron Sun COM>]

Damon/Stefan:

> Thanks. I've committed that, with a few minor changes.

Looks good, with one exception.  In the final else for the ParseStabilityLevel,
you have:

    } else {
        $stability = "";
        print <<EOF;
WARNING: $message is $stability.
It should be one of these: Stable, Unstable, or Private.
EOF
    }

Which clears the $stability value before printing the error message.  The line
$stability = "" should happen after the print statement.

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

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

Brian