Re: Demanding API documentation

[Elijah Newren <newren gmail com>]

On 8/2/05, Luis Villa <luis villa gmail com> wrote:
> 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*

Do you monitor *every commit* to CVS-commits *all year round* to
verify platform modules don't break API/ABI?  I sure don't, and I
don't see why this proposal should require the work if API/ABI
stability doesn't.  I don't think it needs to be monitored in a
draconian fashion; it means everyone does their best to do it and we
get to complain if we discover breakage.

> and (2) which the current platform
> totally fails at, indicating that there isn't much consensus or
> support for it.

I agree that we shouldn't force platform maintainers to stop what they
are doing and suddenly document everything, but what would be wrong
with grandfathering the existing undocumented stuff in the platform
and just requiring this for new API and all new modules that enter the
platform?

Elijah