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

[Damon Chaplin <damon karuna uklinux net>]

On Tue, 2005-01-25 at 01:40, Brian Cameron wrote:
> Damon:
> 
> >>Attached find a patch that implements Stability Levels with the following type 
> >>of command:
> >>
> >>   Stability: [Stable|Unstable|Private]
> >>
> >>With error checking.  If the stability level specified is not one of the above,
> >>it accepts it but prints a warning.
> >  
> > What is the default stability level, if no level is specified? Stable?
> > I don't think we should output the stability level if it is the default.
> > Otherwise it may confuse people. ("Why is this marked stable and that
> > isn't?").
> 
> You are right.  I was initially thinking that making the feature optional made
> the most sense, but that would probably discourage the feature's use.  It would
> probably make sense to have some mechanism to encourage its use.  One way to do
> this would be to make it default to one option, as you suggest.  One
> disadvantage to making the default "Stable" is that would tend to lead to more
> servere error.  You would risk accidently defining an interface as Stable when
> it is in fact Unstable or Private, but just not documented properly with this
> feature in mind.  I would suggest making the default "Unstable" so that a
> conscious action must take place before an interface is defined "Stable".
> I understand that this probably a bit more labor intensive, but I think the
> process benefits would be worth the slight bit of extra work involved.
> 
> So, I made the default in the attached patch "Unstable", but we can change it
> if we think that's better after discussion.
> 
> It might also be useful if a function were not considered "documented" until
> it were given a Stability level.  That might be too severe, so a better approach
> might be to include some statistics in the final report.  Or is there a better
> way?

I don't really think we can ask people to add a stability level to all
pieces of documentation. That is just too much hassle.
So for most GNOME libraries we need to default to "Stable".

Also, I don't see the point in adding "Stability Level: Stable" to
everything in the output documentation, so if it is stable it should be
skipped.

This also doesn't really help the case where the entire library is
considered to be unstable. Something else may be needed there.

Damon