Gentoo Archives: gentoo-portage-dev

From: Bart Lauwers <blauwers@g.o>
To: gentoo-portage-dev@l.g.o
Cc: gentoo-doc@l.g.o
Subject: Re: [gentoo-portage-dev] Re: [gentoo-doc] Re: [gentoo-portage-dev] coveted features
Date: Tue, 30 Dec 2003 00:19:41
Message-Id: 200312300055.47898.blauwers@gentoo.org
In Reply to: Re: [gentoo-portage-dev] Re: [gentoo-doc] Re: [gentoo-portage-dev] coveted features by Jeremy Maitin-Shepard
1 > > Creating documentation automatically always reduces the readability of
2 > > the documentation. It all depends on who's the intended reader. If it is
3 > > a developer (and *only* a developer) then creating documentation
4 > > automatically might be suggesteable (although not official as there is no
5 > > QA on it - don't dare send me bugreports on automatically created
6 > > documentation :)
7 > >
8 > > If it also involves users, then sorry, I don't think this is a good
9 > > idea.
10 >
11 > Indeed, in my experience, documentation generated by Doxygen is very
12 > rarely of decent quality. Provided that people are willing to write
13 > documentation from time to time, ``hand-written'' documentation is
14 > generally of higher quality. If you just want a function reference, it
15 > works, but compare the documentation in linux/Documentation to the
16 > garbage you might get if you were to generate Doxygen documentation from
17 > it.
18
19 Only developer documentation obviously. But auto generated docs don't have to
20 be bad, most of the kde programming docs are done on the fly and they are
21 more then decent. They're also complete and consistent. In terms of API
22 documentation kde rules, can't we mimik this? (And sorry I kinda felt this
23 was obvious in the request but I do mean a documentation level which isn't
24 maintained by the doc team nor meant for general consumption but a reference
25 guide for devs. And then still split in 2 levels, with one for portage
26 development/ integration and one for ebuild developers.) And consumer doc
27 writers are allowed but not forced to use the API level docs for
28 reference. :) (Well I'm convinced it would make things better on a lot of
29 fronts to have tighter code/doc integration but maybe there is a better way.)
30
31 Bart
32
33
34 --
35 gentoo-portage-dev@g.o mailing list

Replies