Re: Demanding API documentation

[Elijah Newren <newren gmail com>]

On 8/2/05, Mark McLoughlin <markmc redhat com> 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. 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.

I think you're looking at it from the wrong angle.  ;-)  Yes, it looks
strange to those who use it but it has a very good purpose: the module
gets no further behind on documentation.  That makes it easier to
require documentation in the future.  It makes it easier for others to
help out.  And it gets us started towards getting things 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. I don't
> want us to get into a situation where every time we identify some
> problem in GNOME we decide that by having the release team issue a
> dictum the problem will magically go away.

I don't think that's fairly representing the situation.  Murray wasn't
trying to provide a dictum; he was asking if there was consensus to go
this route.

>         In order to get to a point where we can be confident that all our
> platform APIs are documented, we need people to prioritise getting the
> documentation for all platform APIs into the same state as gtk/glib. If

Why isn't this a good way to move towards that, though?

> the documentation for a module was in that state, it would be very easy
> for maintainers themselves (rather than the release team) to enforce the
> expectation that new APIs should be accompanied by documentation.

I don't think the release team should have to enforce it, just as they
don't really enforce API/ABI stability, or even really any of the
freezes--we rely on module authors to cooperate (and it's likely that
freeze breakages go unnoticed even now).  The only difference is that
if we do happen to notice something breaking, we can bring it up and
discuss it and try to help resolve the issues.


Just my $0.02,
Elijah