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

[Brian Cameron <Brian Cameron Sun COM>]

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 sun-sac-foss-ext sun com
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