Tworzenie dokumentacji w systemie Doxygen.

Spis treści:

1. Kilka informacji wstępnych.
2. Szybki start w świecie "Doxy".
   • Sposoby komentowania.
   • Doxywizard, tj. minimum wysiłku, maksimum korzyści.
3. Szczegóły związane z plikiem konfiguracyjnym.
4. Możliwości.
   • Znaczniki komentarzy.
   • Tworzenie odnośników.
   • Tworzenie list.
   • Pomijanie komentarzy.
   • Co jeszcze potrafi Doxygen?
5. Czego zrobić się nie da?
6. Porównanie systemów tworzących dokumentację projektu.
7. Przykład kodu skomentowanego dla systemu Doxygen.

Kilka informacji wstępnych

• HTML,
• PDF,
• RTF,
• PostScript,
• format HTML Help (format plików pomocy w środowisku Windows - *.chm),
• XML,
• Man pages (strony dla podręcznika man),
• LaTeX

Szybki start w świecie "Doxy"

Sposoby komentowania

/**
 * Komentarze
 */
			

/*!
 * Komentarze
 */
			

/**
    Komentarze
 */
			

/*!
    Komentarze
 */
			

///
/// Komentarz
///
			

//!
//! Komentarz
//!
			

Doxywizard, tj. minimum wysiłku, maksimum korzyści

Szczegóły związane z plikiem konfiguracyjnym

1. Wygenerować go korzystając z opcji "Wizard..." programu Doxywizard (tak, jak zrobiliśmy to przed chwilą),
2. Skorzystać z opcji "Expert..." Doxywizard,
3. Stworzyć go w linii poleceń na podstawie wzorcowego pliku konfiguracyjnego.
   W podkatalogu "bin" katalogu instalacyjnego znajduje się główny plik programu - "doxygen.exe". Wzór pliku konfiguracyjnego można stworzyć poleceniem:
   

   doxygen.exe -g nazwaPlikuKonfiguracyjnego

   bądź samym:

   doxygen.exe -g

   (wzór zostanie zapisany pod domyślną nazwą "Doxyfile").
   
   Następnie należy wyedytować ten plik i pozmieniać zapisane w nim opcje według uznania (w większości przypadków sprowadza się to do wpisania przy opcji słowa "YES" bądź "NO").
   Aby wygenerować dokumentację wydajemy polecenie:
   

   doxygen.exe nazwaPlikuKonfiguracyjnego

   bądź samo

   doxygen.exe

   jeśli nasz plik nazywa się "Doxyfile".

• Zakładka "Project"
  Podstawowe opcje działania automatu.
• "Build"
  Opcje sposobu tworzenia dokumentacji.
• "Messages"
  Opcje komunikatów.
• "Input"
  Opcje ścieżek do źródeł.
• "Source Browser"
  Opcje cytowania źródeł.
• "Index"
  Opcje tworzenia indeksu.
• "HTML", "LaTeX", "RTF", "man", "XML"
  Opcje tworzenia dokumentacji w postaci (odpowiednio) stron HTML, dokumentu LaTeX, RTF, stron man oraz pliku XML.
• "DEF"
  Opcje generowania definicji AutoGen. W najnowszej wersji (Doxygen 1.5.1) współpraca między Doxygenem a programem AutoGen nie jest jeszcze w pełni zaimplementowana.
• "PerlMod"
  Opcje pozwalające na stworzenie modułu do PERLa, który "przechwyci" strukturę kodu wraz z dokumentacją. Podobnie jak powyżej, opcje te są jeszcze niekompletne.
• "Preprocessor"
  Opcje przetwarzania poleceń preprocesora.
• "External"
  Opcje tworzenia odsyłaczy do zewnętrznej dokumentacji.
• "DOT"
  Opcje wykorzystywane przy tworzeniu grafów zależności między klasami, itp.
• "Search"
  Opcje tworzenia funkcji wyszukiwania w dokumentacji HTML. Należy pamiętać, że do działania wyszukiwarki potrzebny jest serwer z zainstalowanym PHP.

Możliwości

Znaczniki komentarzy

/** @brief Opis skrócony.
 *         Dalej opis skrócony.
 *         Dalej opis skrócony.
 *
 *  Dopiero tu rozpoczyna się opis szczegółowy.
 */

/** Opis skrócony. Opis szczegółowy.
 */

/** Opis skrócony.
 *  Opis szczegółowy.
 */

• @author XYZ
• @date 2006.12.12
• @version 1.0

@exception std::out_of_range Parametr jest poza zakresem.

/**
 * @page strona1 Strona nr1
 * Szczegolowy opis...
 */
/** 
 * Opis...
 * Wiecej informacji znajdziesz tutaj: @ref strona1.
 */

/**
 * Normalny tekst
 *
 * @par Informacje
 * Zawartosc paragrafu
 *
 * @par
 * Nowy paragraf, bez nazwy.
 */

@param i Argument typu int.

@param[out] destination Pamiec do ktorej skopiujemy dane.

@param[in] source Pamiec, z ktorej skopiujemy dane.

/** @relates obslugaNapisow
 * Opis funkcji...
 */

@return Liczba typu float

• \$
• \@
• \\
• \&
• \~
• \<
• \>
• \#
• \%

Tworzenie odnośników

Tworzenie list

/**
 *  A list of events:
 *    - mouse events
 *         -# mouse move event
 *         -# mouse click event\n
 *            More info about the click event.
 *         -# mouse double click event
 *    - keyboard events
 *         -# key down event
 *         -# key up event
 */

• mouse events
  • mouse move event
  • mouse click event More info about the click event.
  • mouse double click event
• keyboard events
  • key down event
  • key up event

/**
 * A list of events:
 * <ul>
 * <li> mouse events
 * <ol>
 * <li>mouse move event
 * <li>mouse click event\n
 * More info about the click event.
 * </ol>
 * <li> keyboard events
 * <ol>
 * <li>key down event
 * <li>key up event
 * </ol>
 * </ul>
 */

Pomijanie komentarzy

• /**
• /*!
• ///
• //!

/*
 * Ten komentarz nie zostanie uwzględniony przez Doxygena 
 */

// Ten też nie

Co jeszcze potrafi Doxygen?

• Jeśli w projekcie są obiekty (klasy, metody, zmienne, itp...), które nie zostały skomentowane, możemy mimo wszystko włączyć je do dokumentacji projektu ustawiając zmienną "EXTRACT_ALL" na "YES".
• Jeżeli włączymy opcję "SOURCE_BROWSER" to z komentarzy znikną te, sformatowane jako dokumentacja kodu dla Doxygena. Pozostałe komentarze się nie zmienią.
• Program ma własny preprocesor kodu C, dzięki czemu komendy preprocesora C (np. #define) zostaną prawidłowo odczytane.
  Opcja ta (ENABLE PREPROCESSING) jest domyślnie włączona w pliku konfiguracyjnym (w wersji 1.5.1).
• Doxygen tworzy automatycznie wykresy dziedziczenia w kodzie wykorzystującym programowanie zorientowane obiektowo. Jeśli potrzebujemy bardziej rozbudowanych wykresów (np. wykresy zależności, współpracy, odwołań), to trzeba skorzystać z narzędzia "dot" z pakietu "graphviz", a w konfiguracji należy włączyć opcję "HAVE_DOT".

Czego zrobić się nie da?

• Doxygen nie obsługuje kilku popularnych języków, np. Perl, SQL, Bash shell scripts, Visual Basic, Ruby,
• Przydałaby się więcej opcji związanych z wyglądem generowanej dokumentacji, np. większe wsparcie dla kaskadowych arkuszy styli,
• Doxygen mógłby modyfikować przy kolejnym generowaniu dokumentacji tylko te pliki, które się zmieniły,
• Dokumentacja HTML nie jest w pełni zgodna z ze standardem XHTML 1.0 Strict,
• Można by rozbudować statystyki dokumentowanego kodu. Mogłyby pojawić się informacje o liczbie zmiennych, metod, klas, średnia liczba linii przypadająca na jeden plik, liczbie globalnych / publicznych zmiennych. Wbrew pozorom, takie statystyki mogłyby być ważne. Np. dla architektów oprogramowania w większych firmach.

Porównanie systemów tworzących dokumentację projektu

Przykład kodu skomentowanego dla systemu Doxygen

/**
 * @mainpage
 * @par About MGallery:
 * Soon more info.
 * @author Mateusz Gurgul
 * @date 2007.02.09
 * @version 1.0
 * @par Contact:
 * If you have any questions, suggestions, etc., please visit my homepage: @a http://www.MateuszGurgul.com
 * @par TODO:
 * See @ref todo
*/

/**
 * @page ClassDiagram Class Diagram
 *
 * @image html ClassDiagram.png "Class Diagram"
 */

/**
 * @page todo List of TODO
 *
 * -# Przemyśleć podejście bazodanowe w kontekście przechowywania plików.
 * -# Wielojęzyczność.
 * -# Warstwa abstrakcji dostępu do bazy (AdoDB).
 *
 * @n Wkrótce lista poszerzy się. @n
 */
 
/// Link file with ConfigurationManager class
require '../ConfigurationManager.php';
/// Create new ConfigurationManager object (singleton)
$config = ConfigurationManager::getInstance();
/// Include all necessary classes
$config->includeAll();

/// Create new front controller object
$MGallery = new FrontController();
/// Run the application
$MGallery->run();

/**
 * Front controller.
 * Główna klasa, kontrolująca wszelkie działania aplikacji.
 * @note FrontController musi być uruchamiany jako pierwszy.
 */
class FrontController implements IController {
	private $config;
	
	/**
	 * Kontruktor front controllera.
	 * @param void
	 * @return void
	 */
	public function __construct() {
		$this->config = ConfigurationManager::getInstance();
	}
	
	/**
	 * Główna metoda front controllera.
	 * Metoda jest uruchamiana przy starcie aplikacji. To tutaj zapada decyzja
	 * którą akcję wykonywać, to tutaj inicjalizuje się zmienne niezbędne w
	 * obiektach akcji.
	 * @n Klasa obsługuje wyjątki, które zgłaszane mogą być w dowolnym
	 * miejscu programu.
	 * Jeśli klasa z obługą wyświetlania błędów nie jest dostępna,
	 * wyświetlany jest niesformatowany tekst informujacy o wystąpieniu błędów.
	 * @param void
	 * @return void
	 */
	public function run() {

		...

	}
}