Dokumentowanie kodu – Doxygen

W tym artykule wprowadzę Cię do systemu dokumentowania, jakim jest Doxygen.

Dwa style tagów
Style komentarzy
Lista najpotrzebniejszych tagów
Doxygen wizard

Jest to system, który nie tylko pozwala zapisać akcje, właściwości, działanie kodu, ale także zająć się sprawami modelowania.
Dobrze skonfigurowany wygeneruje też diagramy klas pokazując również ich relacje.

Doxygen jest znacznie bardziej rozbudowany niż JavaDoc, zawiera dziesiątki tagów więcej, ich pełną listę możesz przejrzeć tutaj.

Zacznijmy.

W tym systemie tagi mogą zaczynać się od jednego ze znaków albo od:
lub od @; oznacza to, że dwa poniższe tagi są równoważne:

      author agilob
      @author agilob

Osobiście wolę drugi sposób oznaczania; taki tag jest lepiej widoczny.

I zajmiemy się tutaj tylko podstawowymi kwestiami dokumentacji, czyli tagami i ich widocznością.

Na potrzeby tego artykułu stworzyłem 3 proste klasy:

  • Human
  • Man
  • Woman

Aby udokumentować metodę możemy używać różnych stylów komentarzy:

/**
brief krótki opis funkcji
 
opis funkcji
todo naprawić
*/
/**
 * @brief krótki opis funkcji 
 * todo naprawić
 * Dłuższy opis funkcji
*/
/*!
 * @brief krótki opis funkcji
 * 
 * długi opis funkcji
*/
///
/// Opis funkcji
///
//!
//! Opis funkcji
//!

Osobiście najbardziej lubię ten używany również przez JavaDoc, dlatego akurat jego będę używał.

Lista najpotrzebniejszych tagów:

  • @author
  • @version
  • @date
  • @param
  • @return
  • @throws
  • @deprecated
  • @see
  • @brief

Kody źródłowe klas wyglądają tak:

[spoiler show=”Pokaż” hide=”Schowaj title=Human.h]

#ifndef HUMAN_H
#define	HUMAN_H
 
/**
 * @brief Gives a draft of human.
 * 
 * Class has methods and attributes which can simulate a real person.
 * 
 * @author God
 * @date 2000.000 years BC
 * @version 1.24 - homo-sapiens
 * @copyright Public domain
 * @warning Person can be an idiot.
 * @pre Environmet must be human-friendly
 * @bug Can't see in darkness
 Can get sick 
 problems with wakeUp()
 * @todo Create anti-age class
 fix bugs
 */
class Human {
public:
   /**
    * @brief Childbirth of new human.
    * 
    * Gives life to a new human.
    */
   Human();
 
   /**
    * @brief Kill human.
    * 
    * If human is too old, it should die, make space for others.
    */
   virtual ~Human();
 
protected:
   /**
    * @brief Lets human move.
    * 
    * Instance of human can change it's position by using this method.
    * 
    * @param x Direction in vertical line on a map.
    * @param y Direction in horizontal line on a map.
    */
   void walk(int x, int y);
 
   /**
    * @brief Human rests.
    * 
    * If a human is tired should take a nap.
    */
   void sleep();
 
   /**
    * @brief Tries to wake-up a human.
    * 
    * Method may fail if human needs more sleep or it's too early.
    * 
    * @param time Wake-up from nap
    * @return If human woke-up - true, otherwise false.
    */
   bool wakeUp(Time time);
 
   /**
    * @brief Gives food to an instance of human.
    * 
    * @param food an object that human will eat
    */
   void eat(Food food);
 
   /**
    * @brief Keeps human alive
    * 
    * If person gets new fresh air
    * @param air New fresh air delivery.
    */
   void breath(Air air);
 
   bool alive; ///< Determines if person is alive or not
   int age; ///< Human's age in years
   float height; ///< Human's height in cm
   string name; ///< Human has a name and surname
 
};
 
#endif	/* HUMAN_H */

[/spoiler]
[spoiler show=”Pokaż” hide=”Schowaj title=Man.h]

#ifndef MAN_H
#define	MAN_H
 
#include "Human.h"
 
/**
 * @brief One from two versions of human
 * 
 * @deprecated Adam - first version of Man
 * @bug balding 
 usually dies before Eve
 * @todo Extend life.
 */
class Man : Human {
public:
   /**
    * @brief A man is born
    */
   Man();
   /**
    * @brief There is a time when a man dies.
    */
   virtual ~Man();
 
private:
   /**
    * @brief ejaculates with sperm
    * @return Sperm to inseminate a Woman
    */
   Sperm fertilization();
 
   Penis p; ///< Describes his penis...
};
 
#endif	/* MAN_H */

[/spoiler]
[spoiler show=”Pokaż” hide=”Schowaj title=Woman.h]

#ifndef WOMAN_H
#define	WOMAN_H
 
#include "Human.h"
 
/**
 * @brief One from two versions of human
 * @deprecated  Eve - first version of Woman
 * @bug mood is based on srand()
 * @todo Fix bug
 */
class Woman : Human {
public:
   /**
    * @brief Newly created human is a woman.
    */
   Woman();
   /**
    * @brief Women die too.
    */
   virtual ~Woman();
 
private:
   /**
    * @brief Will create offspring.
    * @param s object required from man
    * @param o object generated by woman's body
    * @return fetus - new human instance
    */
   Human initializeZygote(Sperm s, Ovum o);
 
   Vagina v; ///< Female human reproductive system
   Breasts b; ///< contains the mammary gland that secretes milk used to feed young humans
 
};
 
#endif	/* WOMAN_H */

[/spoiler]

Jak już widać, klasy Woman i Man dziedziczą od klasy Human kilka metod i atrybutów, co jest również pokazane na wygenerowanym diagramie klas tutaj

Tutaj możemy zobaczyć listę wszystkich zadań do zrobienia w projekcie, jak i listę wszystkich bugów

Jak już pewnie zauważyliście, w komentarze można wstawiać tagi HTML; jeśli chcesz wylistować @todo albo @bug możesz to zrobić używając do tego odpowiednich tagów jak:

<ol>
<ul>
<li>
<br />

Generator dokumentacji

Zapraszam teraz do bardzo szybkiego wprowadzenia do opcji, jakie posiada Doxygen. Jak już wspomniałem, można generować również diagramy klas, jednak to nie wszystko. Rezultatem generatora mogą być też pliki rtf, PDF, źródło LATEX, XML i interaktywne diagramy UML.

Generator pozwala określić wersję projektu, wybrać dla niego logo… no i oferuje wiele, wiele więcej opcji…

Ustawienia Doxygen dla danego projektu można zapisać w oddzielnym pliku, jeśli chcesz zobaczyć przykładowy plik konfiguracyjny, jest on dostępny tutaj.

[Total: 0    Average: 0/5]