[Fwd: Re: Demanding API documentation]

[Murray Cumming <murrayc murrayc com>]

I think the way is now clear for the release-team to demand that all new
Platform API is documented. I suggest that someone in the release-team
adds a rule about it, probably as part of moving the API rules to the
wiki.

Here's a draft:
http://mail.gnome.org/archives/desktop-devel-list/2005-August/msg00003.html

It should also require people to mark deprecated API as such, using
gtk-doc's deprecated tag if possible.
 
-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com

--- Begin Message ---

• From: Mark McLoughlin <markmc redhat com>
• To: Murray Cumming <murrayc murrayc com>
• Cc: desktop-devel-list gnome org
• Subject: Re: Demanding API documentation
• Date: Mon, 28 Nov 2005 10:30:16 +0000

On Mon, 2005-11-28 at 11:18 +0100, Murray Cumming wrote:
> 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.

	Sure, don't let me stop you giving it a shot.

Cheers,
Mark.

--- End Message ---