About Document Generators

Current documentation builder mainly extract informations from :

  • the source code,
  • the source comments.

Both are not equally useful.  In my opinion, the former is for two reasons of little use :

  • the first point is that main informations comming from the sources are navigable files/operations/parameters/etc. lists.  Because this is automaticaly extracted from the code, it’s also available in a good IDE.  For example, when i need the type of some parameter, I just rigth-click on it whitin my IDE.  I don’t even need a fancy graphical IDE, such a feature is available within [x]emacs with the Ada-Mode.  Some more complex doc tools provide graphical views : class dependencies, inheritance, etc.  Here also, an IDE like GPS provide such a view, I don’t need to switch to an external html browser to to check who is calling an operation, or to draw a visibility diagram, it’s integrated.  One has to take care not calling those lists documentation, this is clearly not enough : the essential is missing.
  • the second point is that most interesting informations can’t be automatically extracted from code, because they are not in the code.  For example, it’s impossibe to rebuild the architecture from the code, even with highest semantical level langage available today (I exclude ADL here, because they are not coding languages).  Neither are Design decisions, performance tradeoffs, history, portability, etc., fully in the code.

On the other way interesting informations may be generated from code comments (provided comments exist, obviously :-), or from external documents.

This is a bad news for lazzy programmers : even with modern tools, there is no free lunch.  If you don’t write useful informations, you won’t get useful documentations.  Just pretty and navigable htlmized sources...

This is what pushes me to try Natural Docs : like most of us, I want pretty documents, but I don’t want to write the informations twice.  Lots of informations are useful in the code, so I won’t put them elsewhere.  If Natural Docs enable me to get both pretty documents, informations in the right place, and for a small initial effort, that’s worth a try.