Test Report

I tried to run Natural Docs on the Autolayout package, that illustrate good comments practices in the Software Productivity Consortium (http://www.software.org/) Ada 95 Quality and Style (http://www.adaic.com/docs/95style/html/cover.html).  The Autolayout package is in the 3.3.3 and 3.3.4 chapters (http://www.adaic.com/docs/95style/html/sec_3/3-3-3.html).

The first run produced... nothing.  But with few source modifications, it was much better.

Modifications are :

  • there is only the basic support for Ada in Natural Docs, meaning that I had to put some “Package:”, “Function:” or “Procedure” in the comments.
  • I changed a list syntax.
  • I added a blank line before titles.

No big deal.  Indeed, after those modifications, sources look even better in my opinion (except for the useless “Package:”, “Procedure:” and so on).

Original files are :

Modified files are :

Diff are smalls :

Note that some of the diffs are not really needed, I just wanted to try underscore and bold :-)

All this report is extracted from those sources and some text files, using this command :

NaturalDocs -i $PWD -o FramedHTML $PWD/doc -p $PWD/natural/
  • -i is the sources and text files directory
  • -o is the produced documentation directory
  • -p is the Natural Docs internal data directory.  In this directory, the Menu.txt file is customized.

This is the only modified files outside sources directory : http://lionel.draghi.free.fr/Natural_Docs_Test/natural/Menu.txt .