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

[Brian Cameron <Brian Cameron Sun COM>]

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;