Re: Demanding API documentation

[Murray Cumming <murrayc murrayc com>]

I'm reviving this thread. I want to move forward.

Mark, you were the only maintainer who vetoed this proposal. Have you
changed your views at all? If we don't take this first step, then I'd
don't see what we'll do instead. Another few years of just saying
"developers should document their APIs" isn't likely to have more effect
than it has had for the past few years.

I agree that it would be nice if maintainers just documented everything,
but we know by now that a little process can help them to do the
appropriate thing at the appropriate time.

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. 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.
> 
> _______________________________________________
> desktop-devel-list mailing list
> desktop-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/desktop-devel-list