This is an evaluation of Natural Docs (http://www.naturaldocs.org/) on Ada sources. I discovered Natural Docs thanks to Sam’s paper (http://www.ada-france.org/article106.html) on Ada-France web. I was curious about it: is it possible to get some pretty documentation extracted from the sources, without special tags cluttering the code?
A brief conclusion is that, provided some minor constraints on sources presentation, Natural Docs is useful and easy to use.
Here are the constraints :
1 | for packages/procedures/functions, start the comments with (example for package) : |
-- Package: Autolayout
2 | use the same syntax for your own heading, for example : |
-- Performance:
3 | put a blank comment line after each heading. |
Results at a glance :
Note 1 : those pages are also generated by Natural Docs
Note 2 : in version 1.22, Natural Docs expect Ada file’s suffix to be .ada. You must change ‘ada’ with [‘ada’, ‘ads’, ‘adb’] in the NaturalDocs::Languages::Ada->New call in the NaturalDocs perl script if you want ads/adb files to be processed.
Lionel Draghi, April 04.