Re: Demanding API documentation

[Mark McLoughlin <markmc redhat com>]

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.

	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.

	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.

Cheers,
Mark.