[bind10-dev] API documentation (was Re: DNS packet API: the name object)

[Jeremy C. Reed]

>From our summer 2009 BIND 10 meeting:

pydoc - pythonic way, like javadoc, like docbook
 - use what is normal, keep it simple
 - automated by other installers

doxygen
look at ldns examples (I sent URLs in previous email)
function descriptions, explanations, structures, method calls

need to document overall picture -- how all works together

do README in doxygen ?

TODO: generate doxygen docs (and point Evan and others to it)
- document why, add examples
- don't overdocument, don't underdocument

RFC quotes pasted right in code

BIND 10 docs website include RFCs

describe problem devices or point to NOTE ("war story number 5")

documentation is a process and culture

code needs to commented -- review check that

docs for public interfaces

TODO: Trac have checkboxes for review checklist? (to check docs as part of 
code review?)

Look at PHP documentation examples:
http://www.php.net/manual/en/
http://www.php.net/manual/en/language.namespaces.definition.php
One thing that is interesting is that it includes "add a note" for "User 
Contributed Notes" with feedback for examples and experiences appended to 
end of official docs.

Use openoffice.org for proposals for source editable part. Use PDF for 
sharing.

Get students to write/prepare documentation?