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 |