Developers are an expensive resource and documenting the code manually requires too much precious developer time, also it's a daunting task and very often postponed or even avoided.
Automatic Document Generation saves developers enormous amounts of time and effort by providing instant, detailed and always up to date information on the internals of the code.
Using ROOT it is possible to automatically and continuously update all aspects of the source code documentation, so that the entire team has the all necessary information at their fingertips. Using the information stored in the dictionary and the source files ROOT can automatically generate a source code documentation both in HTML and PostScript® format.
Because of the vast amounts of information in the source code it is often difficult to find the right detail just when you want it. Through highly structured documents, indexed and hypertext linked, developers can navigate quickly and easily to the information that matters. Locating and investigating the code is easier than ever, and of course code reuse too. High quality, indexed and on-line documentation is key to success.
Many prefer to visualize the code, so we provide a graphical representation of inheritance diagrams. In capturing the essence of the code and organizing it logically, ROOT improves the development process significantly with no incremental developer effort!
You need comments placed at the three strategic points in your source code.
Comments behind a data member definition are
stored in the dictionary like a data member description and they
are used whenever data member needs to be described..
The first comment lines after the opening bracket
({) of a member function are considered as a member function description.
A commented block at the top of the source file is considered as a class
description.
First of all you have to be sure that your class (or classes) are properly integrated into ROOT. If that's the case then you can expect no problems at all (of course with a little bit of luck). Here is the small example showing how to create your first HTML file:
1 root> THtml html; 2 root> html.SetOutputDir( "/tmp/doc/" ); 3 root> html.SetSourceDir( "./source/cpp/" ); 4 root> html.MakeClass( "MyClass" ); 5 /tmp/doc/MyClass.html 6 /tmp/doc/MyClass_Tree.ps
As you can see the first thing to do is to create an object of type THtml (line 1). Then we need to decide where to put output files (line 2), but keep in mind that selected output directory must exist and if it doesn't then you have to create one.The third thing is to give a path to your source directories (line 3) , which means that in case you have separate directories for source files (.c, .cpp, .C) and include files (.h .H) your command should look like:
3 root> html->SetSourceDir( "source/cpp/:source/h/" );
Finally (line 4), you are ready to make a class. Your screen output should match the output shown (lines 5 & 6).
Very likely you have written more than one class, and now you want to generate HTML files for all of them. Of course you can follow the same steps you've learned in previous chapter for each of your classes, or you can write a small macro doing it, but using ROOT you have a possibility to make them all at once. Here is the example:
0 root> gSystem.Load("Root_Html.DLL"); // on Windows only 1 root> THtml html; 2 root> html.SetOutputDir( "/tmp/doc/" ); 3 root> html.SetSourceDir( "./source/cpp/" ); 4 root> html.MakeAll( ); 5 -no change- /tmp/doc/MyClass.html 6 -no change- /tmp/doc/MyClass_Tree.ps 7 /tmp/doc/MySecondClass.html 8 /tmp/doc/MySecondClass_Tree.ps
Did you notice that the interface is the same? Great, that's why is so easy. But why we have "-no change-" messages this time? Because, make will look for modifications and it will regenerate files modified since last time only, but if you want to force it to generate all files then you can do it this way:
4 root> html.MakeAll( kTRUE );\
Are you tired setting an output directory and a source path each time you want to run HTML utility? Here is the solution. You have to add two special lines in your .rootrc configuration file.
Root.Html.OutputDir: /home/rootuser/src/html Root.Html.SourceDir: /home/rootuser/src:/home/rootuser/include
Also there is a way to tune ROOT even further. It's always good to know the author's name to whom certain class belongs to. This is possible, but you need to define a format for author's signature used in your source code, which actually means that, for the time being, you have to specify a leading string in front of the author's name. Here is the example:
Root.Html.Author: //----------Author's Name:
In this case ROOT will try to match any line starting with that pattern and everything else in that line will be displayed as author's name, i.e. one correct line should be:
//----------Author's Name: Barton Fink, 1991
It's a same thing for showing your copyright notice or displaying last modified info.
Root.Html.LastUpdate: //----------Modified: Root.Html.Copyright: //----------Copyright:
For additional info, see THtml class description.