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

[Brian Cameron <Brian Cameron Sun COM>]

Damon:

> 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".

I should point out that I'm happy to update the gtk-docs for
libraries that would be the biggest hassle.  In other words, the
libraries that are known to be 100% stable (pango, glib, gtk).
So if the only hang up is that it will be a bit of a hassle for
these libraries, then that shouldn't be such a problem.  Also,
I'd argue that most GNOME libraries are not, in fact, Stable.
We had a discussion on desktop-devel-list and developers seemed
only able to agree that a handful of libraries in the GNOME stack
were really 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.

I do agree with you that it is important to make the feature easy to
use, and I also agree with you that it would be useful to make
shortcuts to avoid having to enter the same "Stability Level: Stable"
entry for every function in a grouping of functions that has the
same stability level.

However, I worry that simply making the default "Stable" and not
printing out any output for the default will discourage its use and
undermine its usefulness.  Can't we think of an approach that
makes the documentation a bit easier without undermining the feature?

Remember that by defining an interface to be Stable, the interface
developer is *guaranteeing* that the interface will not change until
the next major release.  Accidently mislabelling an Unstable or Private
interface as Stable could therefore cause a big problem.  Accidently
mislabelling a Stable interface as Private or Unstable is a much less
severe problem.  In other words, its dangerous to default a stability
level to the most restrictive stability level.  You risk the situation
where a developer uses interface x and thinks it is safe because it is
marked as "Stable", then finds out later that it is really Unstable or
Private and got accidently marked as Stable due to defaults.

Furthermore, as you point out some libraries will be mostly Stable
and other libraries will be mostly Unstable.  Making the default
one or the other makes it easy for some libraries and hard for others.

Perhaps one approach would be to make the default "Undefined" as
was suggested by Peter Williams and not print out anything about
Stability Levels in that case.  This way, stability information will
only be printed for libraries that actually take the time to
document them.

Perhaps a way we could make it easier to document would be to
allow a comment in a file that says "all interfaces in this file
have stability level xyz".  I'm not sure if this is possible
with the way gtk-doc works, but it might be a way to make things
work.

I don't really see a problem with adding the  "Stability Level: xyz"
to every interface in the generated output, but we could perhaps
do something like put a message at the top or bottom of the page
saying "Stability Level: xyz" just once if all the interfaces
on that page are the same level.

Anyway, I've offered some more suggestions about how we could
implement this feature in ways that might be less painful.  Perhaps
we can come up with a creative solution that allows stability
levels to be documented in a way that won't accidently cause
unstable/private functions to get labeled as Stable.  Perhaps
we can also send an email to desktop-devel-list and see what
people think there.  I started a thread there about Interface
Stability and people generally seemed interested in having this
feature.  That way we can get some feedback from the people
the change would impact rather than assuming what would be
considered a hassle and what people consider reasonable.

Brian