Natural Docs reach his goals : it extract pretty docs without special visible syntax in the sources, and is easy to use. It’s definitively a useful tool.
Strong points
- Natural Docs don’t care about legal Ada : Autolayout sources are not compilable Ada.
- There is almost no special formatting glue, a natural text form is OK for Natural Docs. This is a very strong point for me.
- The functions summary is really handy.
Week points
- Natural Docs don’t impose weird comments formatting, but don’t expect any useful doc to be produced from your existing code, unless by miracle you respect Natural Docs rules. For example, in the Autolayout example, there is no blank line between section, and no existing section title is recognized. So, you probably want to determine your comments presentation with Natural Docs in mind before coding start.
What would be useful (in my opinion)
- indexes generated on non-keyword heading. For example, I want to have a “Portability:” topics on each packages. It would be handy to have an index on this (and not only on keywords), so that I can see at a glance packages where there is some thing to do in case of porting.
- enumerated values, and cross reference on it. Here are two examples of useful features :
| 1 | Let’s imagine there is a “Status:” field on each package (maybe automatically inserted by the configuration management system). This status could be Not_Tested, Tested, Reviewed, or whatever. It would be interesting to have a cross reference between Status and Packages, so that one can check quickly which packages are still Not_Tested. |
| 2 | An even more useful application would be requirement traceability. If by just adding heading like “Requirements: SRS_1230, SRS_1300” on comments, Natural Docs could generate a requirement/code cross reference, it would be great! |