Wireshark · Ethereal-dev: Re: [Ethereal-dev] Another small update to docbook

[Ulf Lamping <ulf.lamping@xxxxxx>]

Julian Onions wrote:

>Some of the TVB functions documented now. Mostly just the details from
>the README.
>
>  
>
That's exactly what I tried to prevent :-(

Explaining the API's in three different places: README.developer,
Developer's Guide and doxygen output

In my opinion, all the API descriptions should be done in the doxygen
output. This output should be the API reference, all others only
descriptive help texts pointing to it.

Duplication of text (and simple reformatting) is a bad idea, for source
code and for documentation also.

Keep in mind, that this has to be consistently maintained (all these
three texts), if changes in the API had to be done ...


I don't want to discourage you, but ending up in unmaintained docs is a
thing I really want to avoid.

If you would like to improve documentation in this regard, updating the
tvbuff.h with doxygen tags would be a really good idea, as this is the
way where the docs should be, just *inside* the source files. This way,
there's a chance that the API docs are maintained in the long term.

Regards, ULFL