Damon:
Actually, in my original patch I allow the stability level to be set even if the stability level is not Stable, Unstable or Private. This generates a warning message, but allows people to define additional or more specific stability levels if they want. If they come into general use, they can always be added to the error checking in gtkdoc-mkdb to be allowed. So I think removing the $stability="" completely is actually a better solution.
Also, stability levels only really have meaning if they have defnitions. I gave them definitions here that we could use.
http://mail.gnome.org/archives/gtk-doc-list/2005-January/msg00001.html
It might make sense to put the definitions on the gtk-doc website and in an appropriate file with the gtk-doc distribution (does the README make sense)? If we put the definitions on the web, then we could add the link to where we print "Stable", "Unstable", or "Private" in the docs. That way the developer can click on it and see what it means.
If a module maintainer adds additional definitions, they will probably need to define them somewhere like in their overview until they get added to gtk-doc more formally.
Does this make sense?
Also, it would be nice if people kept the [EMAIL PROTECTED] cc: alias in the thread since it includes interface architects at Sun who have an interest in Free Software stability.
Brian
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
_______________________________________________ gtk-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtk-doc-list
