Re: [gentoo-portage-dev] Re: [gentoo-doc] Re: [gentoo-portage-dev] coveted features

[Jeremy Maitin-Shepard <jbms@gentoo.org>]

Sven Vermeulen <swift@gentoo.org> writes:

> On Mon, Dec 29, 2003 at 06:55:50PM +0100, Bart Lauwers wrote:

> [snip]

>> So let me rephrase that portage docs need to be complete and up to date at
>> all times (at least an english version, devs should know enough english).
>> Linking the documentation to the code is the only way I can see this happen.

> Creating documentation automatically always reduces the readability of the
> documentation. It all depends on who's the intended reader. If it is a
> developer (and *only* a developer) then creating documentation automatically
> might be suggesteable (although not official as there is no QA on it - don't
> dare send me bugreports on automatically created documentation :)

> If it also involves users, then sorry, I don't think this is a good
> idea. 

Indeed, in my experience, documentation generated by Doxygen is very
rarely of decent quality.  Provided that people are willing to write
documentation from time to time, ``hand-written'' documentation is
generally of higher quality.  If you just want a function reference, it
works, but compare the documentation in linux/Documentation to the
garbage you might get if you were to generate Doxygen documentation from
it.

-- 
Jeremy Maitin-Shepard

--
gentoo-portage-dev@gentoo.org mailing list