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

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

Bart Lauwers <blauwers@gentoo.org> writes:

> [snip]

> Only developer documentation obviously. But auto generated docs don't have to 
> be bad, most of the kde programming docs are done on the fly and they are 
> more then decent. They're also complete and consistent. In terms of API 
> documentation kde rules, can't we mimik this? (And sorry I kinda felt this 
> was obvious in the request but I do mean a documentation level which isn't 
> maintained by the doc team nor meant for general consumption but a reference 
> guide for devs. And then still split in 2 levels, with one for portage 
> development/ integration and one for ebuild developers.) And consumer doc 
> writers are allowed but not forced to use the API level docs for 
> reference. :) (Well I'm convinced it would make things better on a lot of 
> fronts to have tighter code/doc integration but maybe there is a
> better way.)

The quality of the documentation produced by doxygen and similar
documentation collectors/generators is generally much higher for very
object-oriented code; this is why the Java standard library
documentation generated by Javadoc is quite usable, and very likely why
the KDE documentation is very good. (I will take your word for it, I
have not looked at it myself.)  If portage-ng is written in a very
object-oriented way, then it is possible that Doxygen-generated
documentation will be of reasonable quality (provided that sufficient
comments are added to the code).  Otherwise, some manually written
documentation describing certain components or the interaction of
certain components would probably be at least a useful supplement.
Indeed, it is in describing the interaction between different
components that generated documentation, even of highly object-oriented
code, is often less useful.

-- 
Jeremy Maitin-Shepard

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