[bind10-dev] about documentation

[Shane Kerr]

Jinmei,

On Wed, 2009-10-14 at 01:12 -0700, JINMEI Tatuya / 神明達哉 wrote:
> At Fri, 09 Oct 2009 12:42:53 -0700,
> JINMEI Tatuya <jinmei at isc.org> wrote:
> 
> > I don't think we need to have a perfect solution at this initial
> > stage, and I'm planning to do provide something anyway.  But if
> > someone can provide a good idea to address the questions and concerns,
> > that would be great.
> 
> ...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.
> 
> I've not shown this to set up the standard.  It's rather intended to
> be a concrete food for discussion.  Is this close to something we're
> expected to write down?  Is it too much or insufficient?  What's
> missing?  How can we keep this consistent with actual implementation
> as development proceeds (or should we bother in the first place)?

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

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

        Every document needs to have at least two things to insure that
        it is kept up to date:
        
             1. An owner
             2. Date next review scheduled
        
        That is actually enough, although a more complicated process may
        be needed in some situations.
        
        An owner is necessary because otherwise documents enter a vague,
        undefined state where they are abandoned and "someone" needs to
        maintain them. The date next review scheduled is needed so we
        can know when to confirm a document is still good.
        
        A "review" can be as simple as reading it and confirming nothing
        has changed. Then the date of next review is updated.
        
        A review also makes sense if the subject the document is about
        has changed. So, if the code is extended, of course the document
        should be updated. The date-based scheduling is to catch cases
        where this is not done for whatever reason; possibly because the
        document is about something external and there is no event to
        trigger the review.

That's it. The same logic applies whether the document is in Subversion
or on the Trac site.

We haven't been doing that so far, because we have been in more-or-less
rapid development. At some point we need to go through all documentation
and assign an owner and a date. I am not sure when this will be exactly;
probably in the next few months. It should not take too long for someone
to do.


I have no opinion about whether the document should be in the Subversion
or in the Trac site (or possibly somewhere else?). It would be to put
design documents like you have on the Trac site - they have versioning
and are in an easily-viewed location. But of course then we have two
locations to look for documentation.

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).



As for the Google-inspired document that you put up... I think it is
quite a good start. It's exactly what we are missing from BIND 9! The
section on NameComparisonResult is especially good, because this is the
kind of thing that is non-obvious and critical to understand.

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.

--
Shane