1 |
Bart Lauwers <blauwers@g.o> writes: |
2 |
|
3 |
> [snip] |
4 |
|
5 |
> Only developer documentation obviously. But auto generated docs don't have to |
6 |
> be bad, most of the kde programming docs are done on the fly and they are |
7 |
> more then decent. They're also complete and consistent. In terms of API |
8 |
> documentation kde rules, can't we mimik this? (And sorry I kinda felt this |
9 |
> was obvious in the request but I do mean a documentation level which isn't |
10 |
> maintained by the doc team nor meant for general consumption but a reference |
11 |
> guide for devs. And then still split in 2 levels, with one for portage |
12 |
> development/ integration and one for ebuild developers.) And consumer doc |
13 |
> writers are allowed but not forced to use the API level docs for |
14 |
> reference. :) (Well I'm convinced it would make things better on a lot of |
15 |
> fronts to have tighter code/doc integration but maybe there is a |
16 |
> better way.) |
17 |
|
18 |
The quality of the documentation produced by doxygen and similar |
19 |
documentation collectors/generators is generally much higher for very |
20 |
object-oriented code; this is why the Java standard library |
21 |
documentation generated by Javadoc is quite usable, and very likely why |
22 |
the KDE documentation is very good. (I will take your word for it, I |
23 |
have not looked at it myself.) If portage-ng is written in a very |
24 |
object-oriented way, then it is possible that Doxygen-generated |
25 |
documentation will be of reasonable quality (provided that sufficient |
26 |
comments are added to the code). Otherwise, some manually written |
27 |
documentation describing certain components or the interaction of |
28 |
certain components would probably be at least a useful supplement. |
29 |
Indeed, it is in describing the interaction between different |
30 |
components that generated documentation, even of highly object-oriented |
31 |
code, is often less useful. |
32 |
|
33 |
-- |
34 |
Jeremy Maitin-Shepard |
35 |
|
36 |
-- |
37 |
gentoo-portage-dev@g.o mailing list |