On 06/30/2010 03:13 PM, Alexandre Julliard wrote:
Erich Hoover<[email protected]> writes:
Alright, well then I won't do it. Is the existing documentation going
to be stripped at some point? It seems to me like we would benefit
from more-detailed function descriptions in the auto-generated API
documentation. I think it would save a lot of time for new developers
to get their feet wet if they were able to see directly in the source
what the different functions are supposed to do (as best as we know)
and exactly what applications will trigger known edge cases (or if
there's a test for a given situation).
That's what the source code and test cases are for. If you rely on the
function documentation you are in trouble anyway, nobody bothers to
update it when new behaviors are discovered.
If you really want to write good API documentation, as opposed to the
current useless one-sentence-per-parameter description, you'd need
probably a text 10 times the size of the source code for each
function. That can't go in the source files.
So, would it be OK with you to extract the current documentation and
put it in the wiki where it can be more easily maintained? Wikis are
supposed to be good for exactly that kind of thing.
Once the wiki is populated with the initial information from the source
code, the source code could then be cleaned up by having links to the
wiki in place of the current cruft.
Erich Hover's tree structure sounds like the right way to go.
Formatting guidelines and templates to tag the article contents so the
information can be easily extracted will be needed, but that belongs on
the wiki, although issues should be discussed and decided on this
mailing list.
