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

[Shane Kerr]

On Mon, 2009-08-17 at 17:31 -0500, Jeremy C. Reed wrote:
> On Mon, 17 Aug 2009, JINMEI Tatuya / 神明達哉 wrote:
> 
> > I'd first like to know what kind of document in which level of detail
> > we're expected to produce as documentation. This is a general
> > question, but to be specific at the moment I'm currently most
> > concerned with the document about the "message API".  For example, are
> > we expected to provide a comprehensive API reference manual like the
> > one for dnsyphtyon?
> > http://www.dnspython.org/docs/1.7.1/html/
> 
> Yes for everything that an outside developer would use.

Indeed... at *least* that much documentation. The later examples you
posted also give hints as to what other documentation might be useful.
Like this:

> But rendered by default to not be on some many different webpages.
> 
> Also I like 
> http://www.unbound.net/documentation/libunbound-tutorial-1.html
> through
> http://www.unbound.net/documentation/libunbound-tutorial-6.html
> (which I believe someone else at ISC pointed out as useful documentation)
> It is more readable and understandable as a "tutorial".



> > Or are we expected to write down source code description?  (If so, it
> > would be a quite heavy task...)
> 
> Probably explanations of code itself is not needed except for decisions 
> made if not clear. I will let others state their needs ...

Well, it depends on what is meant by "description". I don't think
explanations at every line of code make sense of course, but explaining
the overall approach to each module seems like a good investment. In
BIND 9, we have to ask Michael or Mark what the developers were thinking
years ago and hope they remember. Much better if it is written down!

Jinmei, the good news is you have already done this for the DNS packet
API pieces you have put together. It's just a matter of preserving your
ideas more than generating a bunch of new documentation, I hope...

--
Shane