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

[Stefan Kost <ensonic hora-obscura de>]

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
> > gtk-doc-list gnome org
> > 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
> gtk-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtk-doc-list