Re: Demanding API documentation

[Murray Cumming <murrayc murrayc com>]

On Mon, 2005-08-01 at 14:44 -0400, Matthias Clasen wrote:
> On Mon, 2005-08-01 at 20:25 +0200, Murray Cumming wrote:
> > I mentioned this on my blog, but this is a more appropriate place.
> > 
> > Would any platform maintainers object to the release-team demanding
> > that 
> > a) Any new API (functions, signals, properties, etc) in an existing
> > Platform module should have at least some documentation, usually with
> > gtk-doc. Non-public API should be clearly marked, and the documentation
> > should say when new API was introduced (e.g. "since GTK+ 2.6").
> > b) Any new modules going into the Platform should be fully documented,
> > as in a).
> > 
> > This could lead to some delay in the development process, but I think we
> > can deal with that now, and I think it's worth it.
> > 
> > I know a lot of people will scream Yes to this, but we need to know
> > whether anyone objects to this. I'm most interested in Nos from Platform
> > maintainers.
> > 
> 
> How will this work in practise ? Will the release team check all new
> apis for conformance to this rule at the beginning of the api freeze
> period ? 

Good question. Maybe we could have some kind of period between API
freeze and a must-be-documented time. Or maybe we could demand that API
is documented when it's first released in a tarball.

We couldn't depend on the release time to find undocumented API, but we
could allow the release team to complain if they discover it, and make
it clear that documentation is seriously expected. The release-team
doesn't usually have to tell people what to do, but we can make it
clearer what everybody wants.

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