> 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 ...
OK - I guess that was what my original message on the documentation was about.
Where should things be documented. I wasn't aware of the doxygen
stuff, but it sounds a good idea. Given you have doxygen, why describe
the API's in the README files, which is what I copied into the docbook
with some reformating? If doxygen should be considered the master
source for APIs, shouldn't the API descriptions be removed from the
README files (and docbook)?
I had assumed the README files were interim descriptions, with docbook
being the long term goal - and so hence my latest changes. I see that
was an incorrect assumption.
As a developer, I'm now a little confused what I should be reading to
get up to speed. To learn about the API, I can read the docbook, which
now describes how to write a plugin. If I need functions that aren't
mentioned in there, I have to look in the README files, and/or build
doxygen, or just read the source code. tvbuff data for instance can
be found in two different README's and in doxygen.
I guess I'm confused what would be the authorative source to read, and
so where to write any contributions.
The best I can work out is:
Docbook is for descriptive text - how-to type information?.
Doxygen is for API's.
README files are for anything not in the above two - or for interim
data that should probably go in the above eventually.
I'm probably trying to formalise something that doesn't need
formalising, as most developers are happy with the status quo.
Julian.
