Re: [Fwd: Re: Demanding API documentation]

[Federico Mena Quintero <federico ximian com>]

On Tue, 2005-11-29 at 10:41 -0700, Elijah Newren wrote:
> Cool, thanks for doing this Federico.  I took a quick look and just
> made a couple minor changes; it'd be great if others could also have a
> look.

Thanks for the changes; the page is clearer now.

However, I see that you moved the "modules with no new APIs need to have
more of their older APIs documented" part to Recommendations, instead of
Requirements.

The problem with that approach is exemplified in gnome-vfs, libbonobo*,
and other infamous libraries.  Their APIs seldom get additions; they
never get docs.  Eventually the maintainer goes away; and since he is
the only person that knows the API, a few years pass and then we start
saying, "we should deprecate this because nobody understands it".  I've
seen this happen many times throughout the history of GNOME :)

If a library is "done enough" that it doesn't need more APIs, that's the
perfect time to sit down and document all that is missing.

I'd like to move that bit back to Requirements :)

  Federico