WL#4367: Integration of NDB/Bindings Documentation with DynDocs

Affects: Connector/NDB-1.0   —   Status: On-Hold   —   Priority: Medium

NDB API now has three (soon to be more) languages - C++, Java and Python - that
all are essentially the same. We need to produce and manage documentation for
this in a way that scales with the languages, and is still able to catch
per-language differences. 
Had a good meeting with Monty today and I've got a good idea about how we are
going to approach the problem of the NDB/Bindings documentation from a DynDocs
point of view.

There are a number of issues, but the core is:

+ A structure to hold the core data about the original C++ engine
+ A structure to hold information about the differences on a language per
language basis, and on a classname and methodname basis
+ A structure to hold alternative lists of methods (for example, in Java we have
different methods fro different calls to handle default values)

The aim at the moment is to use the information in the SWIG file that defines
these interfaces and pull out the structure, so that we don't have to do it by
hand. Then we'll merge that with the actual text (basically what we have already
in the NDBAPI).

There is, then, a separate issue, which is that we want to be able to merge the
documentation for methods back into the source code so that for languages that
support it, the documentation is right there in the code. This is probably the
most complex part (because the only way to do it is overwrite the source code).

The aim here is not to use comments in the source code as the source of the
material, but to use the source code to help define the structure - you then
fill in the documentation, and we import the official docs into the source so
that we let users make use of javadoc within their IDE, pydoc, perl PD etc. 

My first task will be to structure the XML file and then parse the SWIG source
that will populate that XML file. In theory, the only remaining issue will then
be to merge in the text that we already have (but I'm hoping to simplify that).