Jafar: Code and doc rules

Code rules in short

We use java like conventions for names of namespace, class, variable, method, ... For the filenames, we use names starting with a lowercase character, extension for header is .hpp and for source .cpp. Makefiles are based on these conventions...

Do not forget:

to protect header files from multiple inclusion using #ifndef MODULE_FILE_HPP
to declare your classes and functions in the according namespace jafar::module

For the C++ templates please refer to About templates.

About namespace

In jafar framework, we assume the name of a module to be unique, but names of classes or functions do not have to be prefixed by the name of the module. To avoid names conflicts between modules, we made extensive use of namespaces:

everything that belongs to jafar must be in jafar namespace,
every module must enclose all its declaration in a jafar::module namespace.

Use of debug message

When you want to have debug messages printed out, you have to put in your code some (a lot ?!) printf() or cout << protected with #ifndef NDEBUG... In Jafar, we strongly recommend to use the jafar::kernel::JafarDebug throught the JFR_DEBUG(message) macro.

And do not forget that some debuggers are out there...

Doc rules in short

The documentation is generated by doxygen from:

.hpp headers in include/module,
and from .doxy files in doc/doxygen.

Please read doxygen doc FIXME for more information. Doxygen can parse comments written in the javadoc style, if you already know this syntax this is fine, but doxygen is a step ahead more powerfull ;-). Jafar documentation takes advantage of the group feature of doxygen to put documentaion from the same module together in the same doxygen group. To achieve this, do not forget to put the \ingroup command to the comments of your classes or your functions.

The whole doc is generated in the html format using the doxygen command in your $JAFAR_DIR. If doxygen is in your path:

$ cd $JAFAR_DIR
$ doxygen

The configuration file Doxyfile will be found automatically. The doc is generated from the installed modules (subsecFrameworkMakefile) and from jafar documentation in $JAFAR_DIR/doc/doxygen.

Also have a look at the command output and please correct errors and warnings !

Documenting errors

FIXME


\pre \post \invariant \throw

Documenting TCL macros

All files in macro/ must be documented at two level:

Each file must be shortly documented so that doxygen includes it on the module page. This is a bit weird since doxygen cannot really parse .tcl files, documentation should lay on a single comment line (to avoid extra # in the generated documentation).
Each tcl procedure must be documented so that the help function from help.tcl can retrieve a help message. The documentation should follow the proc declaration and can be split on several lines.

An example (from demoHello.tcl):

# $Id$ #

#
#/** demo macro for HelloWorld class. \file demoHello.tcl  \ingroup helloworld */
#

package require helloworld

namespace eval helloworld {

    proc demoHello { n } {
        # this is a demo tcl procedure
        # create n HelloWorld object and print them
        for {set i 0} {$i<$n} {incr i} {
            set h [helloworld::new_HelloWorld "Hello world ! ($i)"]
            $h printHello
	    helloworld::delete_HelloWorld $h
        }
    }

}

package provide helloworld 0.3

Header example (.hpp)

From the module helloworld, the class jafar::helloworld::HelloWorld in the helloWorld.hpp file. Header files must be in the include/module/ directory of the module.

/* $Id$ */

#ifndef HELLOWORLD_HELLO_WORLD_HPP
#define HELLOWORLD_HELLO_WORLD_HPP

#include <string>
#include <ostream>

#include "kernel/jafarException.hpp"

#include "helloworld/helloworldException.hpp"


namespace jafar {

  namespace helloworld {

    class HelloWorld {

    private :
  
      std::string hello;

      static bool checkHello(const std::string& hello_);

    public :

      HelloWorld();

      HelloWorld(const std::string& hello_);

      ~HelloWorld();

      const std::string& getHello() const;

      void setHello(const std::string& hello_);

      void clearHello();

      void printHello();

      friend std::ostream& operator <<(std::ostream& s, const HelloWorld& h_);

    }; // class HelloWorld

    std::ostream& operator <<(std::ostream& s, const HelloWorld& h_);

  } // namespace helloworld
} // namespace jafar

#endif // HELLOWORLD_HELLO_WORLD_HPP

Source example (.cpp)

The implementation of this class in the file helloWorld.cpp. Source files must be in the src/ directory of the module.

/* $Id$ */

#include "helloworld/helloWorld.hpp"
#include "kernel/jafarDebug.hpp"

using namespace std;

using namespace jafar::helloworld;

HelloWorld::HelloWorld() : hello() {
  JFR_VDEBUG("HelloWorld object created");
}

HelloWorld::HelloWorld(const string& hello_) :
  hello() 
{
  JFR_VDEBUG("HelloWorld object created");
  setHello(hello_);
}

HelloWorld::~HelloWorld() {
  JFR_VDEBUG("HelloWorld object destroyed");
}

const string& HelloWorld::getHello() const {
  return hello;
}

void HelloWorld::setHello(const string& hello_)
{
  JFR_PRECOND(hello_.size() > 0, "HelloWorld::setString: empty string");
  if (!checkHello(hello_)) {
    throw HelloworldFormatException(hello_, 
                                    "message should begin with \"Hello\"", 
                                    __FILE__, __LINE__);
  }
  hello = hello_;
  JFR_DEBUG("set hello message to \"" << hello_ << "\"");
}

void HelloWorld::clearHello() {
  hello.clear();
}

void HelloWorld::printHello()
{
  if (hello.size() > 0) {
    cout << hello << endl << flush;
  }
  else {
    JFR_ERROR(HelloworldException, HelloworldException::EMPTY_HELLO, "hello is not initialized");
  }

}

bool  HelloWorld::checkHello(const string& hello_) {
  JFR_DEBUG("check hello string: \"" << hello_ << "\"");
  return (hello_.substr(0,5) == "Hello");
}

std::ostream& jafar::helloworld::operator<<(std::ostream& s, const HelloWorld& h_) {
  s << "Hello string: " << h_.hello;
  return s;
}

About templates

Templates are a special feature of the C++ language which enables generic programming. The templates are fully contained in headers files, and can be defined in two different ways:

directly in the class declaration,
after the class declaration.

The syntax of the second method is a bit weird, so we advice people to use the first one.