[bind10-dev] about documentation

[JINMEI Tatuya / 神明達哉]

At Wed, 14 Oct 2009 12:25:45 +0200,
Shane Kerr <shane at isc.org> wrote:

> > ...okay, for the "something", I've summarized the design discussions
> > so far and a bit detailed version of API specifications for the name
> > class in a trac page:
> > http://bind10.isc.org/wiki/NameClassDesign
> > 
> > It's largely derived from the organization of the google "designdoc"
> > example, but is slightly adjusted for the context of our case.

> As usual, you have done excellent work. It makes me very, very happy. :)

Thanks, although I'm afraid if I can keep the same quality and
quantity for subsequent documents:-)

> So, for a question you asked in the last e-mail, let me give my basic
> idea about document maintenance:

[details snipped]

This looks fine to me.

> For the actual API documentation, we probably want to use pydoc for
> Python:
> 
>         http://docs.python.org/library/pydoc.html
> 
> And probably doxygen is the way to go for C++:
>         
>         http://www.stack.nl/~dimitri/doxygen/
> 
> Surely there is some clever way to publish this on a Trac site. We can
> always set up a separate section on https://bind10.isc.org that gets API
> documentation generated from such mechanisms (like
> https://bind10.isc.org/doc/api or the like).

[snip]

> The only real concern I have is about putting the actual class
> definition in the document. But of course it is *so* much easier to
> understand if you see code. Perhaps we can just put the Subversion
> revision as a note, or maybe as a link like this:
> 
> http://bind10.isc.org/browser/experiments/jinmei-messageapi/dnsname.hh?rev=87
> 
> This way readers will not be agitated if the documentation doesn't match
> the latest code - the reason will be more-or-less obvious.

I have this concern, too.  So I believe code specific descriptions
such as class definitions should directly be documented in the source
file and we should general an HTML file from it and have the trac site
refer to it.  We should also automate this process.

Regarding markups, I don't know if doxygen is the best tool.  Jelte
said on jabber it was not so good to document API specifications
(probably based on his own experiences).  I used doxygen for BIND9 but
since we've not actually transformed the doxygen markups into other
readable formats I have no experience with it in practice.  Maybe I
should first try doxygen anyway and see if it works or we need
something else.

---
JINMEI, Tatuya