Re: Demanding API documentation

[Murray Cumming <murrayc murrayc com>]

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?

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

-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com