On Mon, Apr 23, 2007 at 04:27:34PM -0700, Steve Langasek wrote: > > > On 23-Apr-07, 15:51 (CDT), Neil Williams <[EMAIL PROTECTED]> wrote: > > > > I think that all libraries - without exception - must come with some > > > > API documentation and the docs should be as complete and as accurate > > > > as possible - ideally generated from the source itself. > That the existing requirement is already too much for us to keep up with, so > adding new requirements, especially ones that require significant attention > to detail to get right, dilutes our attention for little benefit?
If we are talking about hand-written documentation you're of course right. However if you're talking about documentation which can be generated automatically from sources (and not that it was the "ideal" point of Neil) than you're not. It happened to me many times to find library -dev packages with upstream sources commented with some literate programming stuff but nevertheless missing the corresponding automatically generated API docs in the package. That's a pity. And that's something the policy should address. Often, even when comments are not properly formatted, doc generation tools can generate useful documents which complements .h files or similar stuff in other languages. Cheers. -- Stefano Zacchiroli -*- PhD in Computer Science ............... now what? [EMAIL PROTECTED],debian.org,bononia.it} -%- http://www.bononia.it/zack/ (15:56:48) Zack: e la demo dema ? /\ All one has to do is hit the (15:57:15) Bac: no, la demo scema \/ right keys at the right time
signature.asc
Description: Digital signature
