Re: [Fwd: Re: Demanding API documentation]

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

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 :)


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]