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

[Brian Cameron <Brian Cameron Sun COM>]

Damon/Stefan:

> On Thu, 2004-12-30 at 11:50, Stefan Kost wrote:
>
> > hi hi,
> >
> > another entry for future changes:
> > Currently gtkdoc only adds undocumented symbols to xxx-undocumented.txt. If one
> > has undocumented function parameters, or undocuments struct-members, enum-values
> > ..., this is not recorded.
> > I would prefer this been part of the undocumented file as well, e.g. in the form of:
> >
> > my_function param_1
> > my_function param_5
> >
> > or alternatively
> >
> > my_function
> >  param_1
> >  param_5
>
>
> I think it would be enough to add it to xxx-undocumented if any
> parameters/struct members at all weren't documented.
> Do we really need to know exactly which parameters/members aren't
> documented? 

If you think it adds value to include it in the output, then I'd say go for
it.  However, I agree with Damon and think that just highlighting that there
is a problem with the documentation for a given function is enough of a
pointer.  Does it also display a warning message at gtk-doc runtime?  If so,
including the detailed information there might be more useful.

Not sure if people noticed that there was a discussion on desktop-devel-list
last month concerning Interface Stability in GNOME.  Much of the discussion
involved trying to get a better feel for what stability classifications make
the most sense for the GNOME community.  In that discussion I mentioned the
levels that we use at Sun, and some people responded giving us some
perspective on what sort of stability levels might make sense for GNOME.
You can read the thread here:

http://mail.gnome.org/archives/desktop-devel-list/2004-December/msg00752.html

It seems that "Stable", "Unstable", and "Obsolete" are three classifications
that seemed to relate best to the way most of GNOME works.  There was some
discussion that a "GNOME Private" interface might also be useful.  These
classifications have the following meanings:

+ Stable - The intention of a Stable interface is to enable arbitrary
  third parties to develop applications to these interfaces, release
  them, and have confidence that they will run on all minor releases
  of the product (after the one in which the interface was introduced,
  and within the same major release). Even at a major release,
  incompatible changes are expected to be rare, and to have strong
  justifications.

+ Unstable - Unstable interfaces are experimental or transitional.
  They are typically used to give outside developers early access
  to new or rapidly changing technology, or to provide an interim
  solution to a problem where a more general solution is anticipated.
  No claims are made about either source or binary compatibility from
  one minor release to the next.

  Any documentation for an Unstable interface must contain warnings
  that these interfaces are subject to change without warning and
  should not be used in unbundled products.

  Given such caveats, customer impact need not be a factor when
  considering incompatible changes to an Unstable interface in a
  major or minor release. Nonetheless, when such changes are introduced,
  the changes should still be mentioned in the release notes for the
  affected release.

+ GNOME Private - An interface that can be used within the GNOME
  stack itself, but that is not documented for end-users.  Such functions
  should only be used in specified and documented ways.

+ Internal - An interface that is internal to a module and does not
  require end-user documentation.  Functions that are undocumented are
  assumed to be Internal.

However, it was clear after the discussion that there is a potential
spectrum of classification levels, which depend mostly on the commitment
level that a module owner wants to make with a user.

In my earlier proposal, I suggested that we enhance gtk-doc so that
interface stability levels can be defined along with the functions.  I
suggest that we make use of the above list of keywords and meanings.

However, I think it would also be appropriate to make it possible for
a module owner to define their own stability levels and use them.
Perhaps the module owner could create a file with a specific name
in the module.  This file could contain a list of strings (or Stability
Levels).  These additional strings could be used for validating that
the value given for "Interface Stability Level" are valid values.

Does this seem like a reasonable approach?

--

Brian