Re: Demanding API documentation

[Luis Villa <luis villa gmail com>]

On 8/2/05, Murray Cumming <murrayc murrayc com> wrote:
> On Tue, 2005-08-02 at 08:01 +0100, Mark McLoughlin wrote:
> > Hi Murray,
> >       Firstly, I don't think we could even consider getting this draconian
> > about interface documentation until all the *existing* interfaces are
> > documented.
> 
> Yes, but I have the hope that, if we show that there's consensus about
> the need for documentation in this case, then there will be strong
> pressure to document the other stuff too. However, some of the older
> stuff is genuinely difficult to document unless you are the original
> author -for instance, GTK+ signals.
> 
> >  If a whole library was pretty much undocumented, it'd be
> > bizarre to prevent the addition of one new function on the basis that
> > that function isn't documented.
> >
> >       Secondly, I don't believe that the release team becoming more draconian
> > about a specific weakness is the best way to fix that weakness.
> 
> Sure, but
> a) The release team do document and explain the expectations of our
> various release sets.
> b) Is there a better way?

Maybe actual consensus that people voluntarily buy into and do on
their own? The release team has very limited resources, and of late
we've had trouble getting releases out, much less actually enforcing
freezes. And we've never competently reviewed patches, much less
capably kept an eye on cvs-commits. It isn't sane to introduce a huge
new responsibility, which (1)  would require reading *every commit* to
CVS-commits *all year round* and (2) which the current platform
totally fails at, indicating that there isn't much consensus or
support for it.

Luis