Brian,
it might be better if you open a bugzilla issue and attacht the patch to that.
Stefan
Damon:
On February 4th I send the following email with attached 2-line patch that adds "@stability" to the section docs in the source code. I notice this hasn't made it into CVS head and wanted to remind you to consider including this as well. I think it's pretty much the last piece needed to support stability levels in gtk-doc.
Also, in previous emails I suggested that it probably makes sense to put default definitions of the three stability levels (Stable, Unstable and Private) somewhere. Perhaps on the web, perhaps as a part of the generated gtk-docs. This way people can look up the default meanings of the interface levels. Haven't gotten any response about whether people agree this is a good idea or not. Perhaps this isn't the right list. If it makes the most sense to put this sort of information somewhere on developer.gnome.org, what would be the right alias to discuss this?
Brian
Damon:
Attached please find a patch which adds "@stability" to the section documentation in the source code. I've tested CVS head with this patch and it looks like everything is working well.
In my last email, I mentioned that Stability levels really only have meaning if they are well defined, and I suggested that perhaps we could consider putting the definitions on the gtk-doc website somewhere. Then the keywords "Stable", "Unstable", and "Private" could like to the definitions instead of just being bare words. Alternatively, we could include some html with the definitions in the output so the defnitions get included with the generated output. Not sure which approach makes the most sense. I'm hoping you'll be able to give a suggestion about how to best do this.
Brian
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
------------------------------------------------------------------------
Index: gtkdoc-mkdb.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
retrieving revision 1.114
diff -u -r1.114 gtkdoc-mkdb.in
--- gtkdoc-mkdb.in 4 Feb 2005 14:18:05 -0000 1.114
+++ gtkdoc-mkdb.in 4 Feb 2005 20:22:19 -0000
@@ -2470,6 +2470,8 @@
$SourceSymbolDocs{"$TMPL_DIR/$real_symbol:See_Also"}=$params[$k+1];
} elsif ($params[$k] eq "title") {
$SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Title"}=$params[$k+1];
+ } elsif ($params[$k] eq "stability") {
+ $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Stability_Level"}=$params[$k+1];
}
}
$SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Long_Description"}=$description;
------------------------------------------------------------------------
_______________________________________________ gtk-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtk-doc-list
------------------------------------------------------------------------
Index: gtkdoc-mkdb.in =================================================================== RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v retrieving revision 1.114 diff -u -r1.114 gtkdoc-mkdb.in --- gtkdoc-mkdb.in 4 Feb 2005 14:18:05 -0000 1.114 +++ gtkdoc-mkdb.in 4 Feb 2005 20:22:19 -0000 @@ -2470,6 +2470,8 @@ $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:See_Also"}=$params[$k+1]; } elsif ($params[$k] eq "title") { $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Title"}=$params[$k+1]; + } elsif ($params[$k] eq "stability") { + $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Stability_Level"}=$params[$k+1]; } } $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Long_Description"}=$description;
------------------------------------------------------------------------
_______________________________________________ gtk-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtk-doc-list
_______________________________________________ gtk-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtk-doc-list
