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). MC
Copyright (c) 2000, 2017, Oracle Corporation and/or its affiliates. All rights reserved.