Code Documentation

TerraLib has a configuration file to generate the API documentation through the Doxygen.

Doxygen is a documentation system for C++ and many others programming languages.

The Doxygen provides a HTML on-line documentation generation of a project, well as providing a offline documentation through a PDF file or a simple DOC using tools like Latex.

Moreover, Doxygen is able to generate diagrams based on class hierarchy, and you can make them more attractive by using tools like Graphviz.

Below there are links to download the Doxygen and other tools:

• Doxygen
• Graphviz

Here we can see some examples of documentation required to generate the Doxygen documentation. Most of these examples are excerpts from the TerraLib code.

To document a class, you can start using tags like \file, \class, \brief, \details, \version, \author, \date and \copyrights as exemplified below:

/*!
  \file TerraLib.h
 
  \brief Starts a paragraph that serves as a brief description
  \details starts the detailed description that you can write more about your code.
  HTML tags are accepted:
  <ol>
    <li>You can, and should, use the most common HTML tags, like
    "<b>", "<i>", "<ol>", "<li>", "<img>", etc...</li>
    <li>If you use resources you should remember to copy it
    to the folder doc.</li>
    <li> You can also use the tag "\snippet" of Doxygen to put 
    some code example.</li>
  </ol>
  \version 1.0
  \author your_name <your@e-mail.com>
  \date
  \copyright GNU Lesser General Public License.
 */
 
#ifndef __TERRALIB_COMMON_INTERNAL_TERRALIB_H
#define __TERRALIB_COMMON_INTERNAL_TERRALIB_H
 
// TerraLib
#include "Config.h"
#include "Singleton.h"
 
// STL
#include <string>
#include <vector>
 
/*!
  \class TerraLib
 
  \copydoc Terralib.h  //This tag copy the \brief and the \details of the file
*/
 
  class Terralib
  {
  public:
    /*! 
      \brief Constructor.    
      \details The default constructor.
    */
    Terralib();
 
    /*! 
      \brief Destructor.
    */
    ~Terralib();
  };

This command can be used to quote only a fragment of a source file

To use a \snippet you will call a unique identifier of a file, you should reference the file and directory.

The root is setted in the EXAMPLE_PATH in the Doxygen configuration file.

You will call the \snippet like this:

\snippet examples/snippets/example.cpp Adding a resource

The text following the file name is the unique identifier for the snippet. This is used to delimit the quoted code in the relevant snippet file as shown in the following example that corresponds to the above \snippet command:

    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));
//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...

Note that the lines containing the block markers will not be included, so the output will be:

document->addResource(QTextDocument::ImageResource,
    QUrl("mydata://image.png"), QVariant(image));

To register the existence of a bug in the code we use the tag \bug, well as the warnings the tag \warning.See the example:

/*!
  \brief Execute an operation 
 
  \param str The string that will be added.
 
  \warning This method can provide run-time errors
 
  \bug Method returning invalid value
*/
int execute();

The bugs recorded using the tag \bug will be displayed in the class information tab and will be entered in a bug list, accessed from the tab “Related Pages”.

To register as a deprecated method is used the tag “\deprecated” as in the example:

/*!
  \brief Add a string
 
  \param str The string that will be added.
 
  \deprecated This method will be removed in the near future.
*/
void add(const std::string & str);

For registrate a example of a class, that is in the example path, you might use the tag \example. The tag \example will create a “Examples” tab in the documentation and put the link for the file.

• /*!
        \class ColorBar
   
        \brief It models the concept of color bar.
   
        It is used to construct color bar.
   
        \example colorbar/main.cpp
   
       */
      class TECOLOREXPORT ColorBar
      {
   
  ...

Now, if you want to insert a direct link to the example in the documentation of the class, you can use the tag \link, as shown below:

• /*!
        \class ColorBar
   
        \brief It models the concept of color bar.
   
        It is used to construct color bar.
   
        \link colorbar/main.cpp ColorBar: Usage Example     
   
        \example colorbar/main.cpp
   
       */
      class TECOLOREXPORT ColorBar
      {
   
  ...

You can create a especific group to your methods, like “Initializer Methods”, “Accessor Methods”, “Private Methods”, in order to organize more the code.

You'll use the tag \name before a group of methods. This command turns a comment block into a header definition of a member group. The comment block should be followed by a

 //@{  
  Your code here
  //@}

block containing the members of the group.

Example:

  /*! \name Initializer Methods
   *  Methods related to instantiation and destruction.
   */
 
  //@{
 
  /*!
  \brief It initializes a new ColorBar.
  \param parent
  */
 
  ColorBar(QWidget* parent = 0);
 
  /*! 
  \brief Destructor 
  */
 
  ~ColorBar();
 
  //@}
 
 
  /** \name Accessor methods
   *  Methods used to get or set properties.
   */
 
  //@{
 
  /*!
  \brief Sets the height of colobar.
  \param Value of height.
  */
 
  void setHeight(int value);
 
  //@}
 
 ...

When you document a file in which the name may be shared by others files in others directories, it is very recommended the addition of a part of the path in the tag “\file”, instead put only the file name.

Example:

/*!
 
\file terralib/common/Config.h
 
\brief
 .....
 
*/

• To generate the TerraLib documentation you must install the Doxygen 1.7.4 or above.
  • Download Doxygen
• Open the wizard (Doxywizard)
• Go to File/Open and select the TerraLib Doxygenfile on repository (terralib5/doc/Doxyfile.txt).
• All settings contained in the Doxyfile will be available to changes
• Go to the “Run” tab and select “Run doxygen”
• With the default settings the documentation will be generated in terralib5/doc/api folder.
• To view the documentation enter the folder “html” and open the index.html file (terralib5/doc/api/html/index.html).

Graphviz is open source graph visualization software that take descriptions of graphs in a simple text language, and make diagrams in useful formats. Doxygen generates diagrams, but the diagrams generated by Graphviz can be more pleasant and there are many others options.

To use the “Graphviz” for the generation of documentation is required:

• Install the Graphviz 2.28.0 or above
  • Download Graphviz
• Make sure that the path of the binaries have been added in the environment variable “path”
• Open the wizard (Doxywizard)
• Go to File/Open and select the TerraLib Doxygenfile on repository (terralib5/doc/Doxyfile.txt).
• Select the “Wizard” tab
• Go to topic “Diagrams”
• Select “Use dot tools from the GraphViz package”
• Choose the options or leave default
• Generate the documentation

• Doxygen Manual