Wednesday, 07 January 2009 arrowHome Add to Technorati Favorites
Main menu
Home
Articoli
RSS news
Saputello
Segnalazioni
Info
The Four Keys
Info sullo speciale
Approfondimenti sul codice
C++, STL, Design Pattern
OpenGL, SDL e Computer Graphics
Artwork




Guida Doxygen E-mail

Comandi standard

Con Doxygen possiamo documentare praticamente tutto, dalle classi, alle funzioni, dai namespace, alle variabili, dai typedef fino ai singoli valori di una enum:

 

// ----- file HPP -----

 

/*! \brief Descrizione breve della mia classe

 * Continua la descrizione breve sulla stessa linea

 *

 * Descrizione dettagliata della mia classe

 * \note Qui puoi inserire delle note

 * \bug Qui puoi inserire la lista dei bug

 * \todo Qui puoi inserire la lista delle cose da fare

 * \sa Vedi anche Window */

class Widget {

public:

  //! Evento tasto

  typedef enum {

    KeyPressed, //!< Tasto premuto

    KeyReleased //!< Tasto rilasciato

  } EKeyEvent;

 

  //! Costruttore

  /*! \bug Bug del costruttore */

  Widget()  { Size.W=Size.H=Position.X=Position.Y=0; }

 

  //! Distruttore

  virtual ~Widget() {}

 

  /*! \brief Funzione virtuale che disegna il widget

   *

   *  Spiegazione dettagliata di cosa fa questa funzione

   *  \todo Cose da fare per questa funzione */

  virtual void Draw() = 0;

 

  //! \brief Gestisce gli eventi del mouse

  virtual void EventoMouse() = 0;

 

protected:

  //! Dimensione del widget

  /*! Dettagli vari */

  struct {

    int W; //!< Larghezza. Documenta singoli campi di una struct

    int H; //!< Altezza

  } Size;

 

  struct { int X, Y; } Position; //!< Commento a lato

};

 

/*! \brief Implementazione di una finestra generica

 * \bug Qui puoi inserire la lista dei bug di questa classe

 * \todo Qui puoi inserire la lista delle cose da fare

 * \sa Vedi anche Widget */

class Window: public Widget {

public:

  //! \brief Disegna la finestra

  virtual void Draw();

 

  //! \brief La descrizione breve e' divisa dalla descrizione lunga

  Widget* addWidget(Widget * w);

};

 

// ----- file CPP -----

 

/*! La descrizione lunga puo' essere messa insieme all'

 * implementazione per rendere l'interfaccia della classe

 * piu' leggibile

 * \param w Descrizione del parametro w

 * \return Descrizione del valore di ritorno */

Widget* Window::addWidget( Widget* w) {

  return NULL;

}

Vedi la documentazione generata


L'esempio sopra riportato mostra dei nuovi comandi:

  • \note - Crea una sezione intitolata "Note" in cui è possibile inserire commenti di particolare rilievo.

  • \bug - Crea una sezione intitolata "Bug" in cui è possibile elencare eventuali problemi relativi all'entità in questione.

  • \todo - Crea una sezione intitolata "Todo" in cui possiamo compilare una lista delle cose da fare.

I comandi "\bug" e "\todo" sono di particolare utilità dato che Doxygen crea due pagine speciali "Bug list" e "Todo list" all'interno della sezione "Related Pages", in cui sono elencati tutti i bug del progetto e tutte le cose da fare, con tanto di riferimenti ipertestuali alle entità coinvolte (classi, funzioni, etc.).

  • \sa - Crea una sezione intitolata "See also" in cui possiamo inserire gli argomenti correlati all'entità che stiamo documentando. Si noti che nell'esempio riportato sopra, la parola "Widget" viene riconosciuta automaticamente come identificatore di una classe e quindi nella documentazione tale parola è collegata alla relativa pagina della classe "Widget".

L'esempio mostra anche come Doxygen riconosca le funzioni virtuali e le loro reimplementazioni. Ad esempio la documentazione del metodo Widget::Draw() riporta quali classi la reimplementino (nel nostro caso Window). Similmente la documentazione del metodo Window::Draw() riporta l'ultima classe nella gerarchia di Window che ha implementato tale metodo (Widget). A questo proposito una funzione estremamente utile di Doxygen è "List of all members" presente nella documentazione di tutte le classi. Selezionando tale voce Doxygen presenta una lista di tutti i membri di una classe inclusi quelli ereditati da altre classi (mostrando anche da quali).

 

Per mantenere più pulita l'interfaccia di classi e funzioni Doxygen ci permette di dividere la descrizione breve ("\brief") da quella dettagliata. Nell'esempio questa tecnica viene usata per la funzione Window::addWidget().

 

Ci sono occasioni in cui è più pratico scrivere la documentazione di una entità non sopra di essa ma accanto ad essa. Questo è spesso il caso dei valori di una enum o dei singoli campi di strutture o classi. Per fare ciò basta apporre il simbolo "<" subito dopo l'inizio di un blocco Doxygen, ad esempio "/*!<" o "//!<".


Altri comandi che è utile conoscere:

  • \deprecated - Similmente a "\bug" e "\todo" crea una lista di classi, funzioni etc. non più supportate ma mantenute temporaneamente per compatibilità (deprecate appunto).

  • \internal - Consente di marcare come "interno" un blocco di documentazione. I blocchi "interni" possono poi essere inclusi o esclusi dalla documentazione in base al fatto che essa sia destinata agli utenti o agli sviluppatori.

  • \verbatim - Il testo compreso tra questo comando e "\endverbatim" viene copiato parola per parola nella documentazione. Tutti i comandi Doxygen inclusi in tale blocco sono disabilitati.

  • \code - Il testo compreso tra questo comando e "\endcode" è trattato come codice C/C++. Doxygen collega le entità incluse in questo blocco alla rispettiva documentazione.

  • \author - Crea una sezione in cui possiamo specificare l'autore o gli autori di una classe, funzione etc.

  • \version - Crea una sezione in cui possiamo specificare la versione di una classe, funzione, modulo etc.

  • \date - Crea una sezione in cui specificare una data.

  • \warning - Crea una sezione intitolata "Warning" in cui possiamo evidenziare particolari avvertimenti.

  • \\, \@, \$, \%, \<, \>, \# - Servono a generare rispettivamente i caratteri \, @, $, %, <, >, #.

 

Questi sono solo alcuni dei comandi più usati, nella sezione Special Commands del manuale di Doxygen è possibile consultare l'elenco di tutti i comandi disponibili.


 
< Prev   Next >



I più letti
Suggerimenti Google
Novità
© 2006-2007 Michele Bosi
E' vietata la riproduzione, anche parziale, di contenuti e grafica
Ottimizzato per Firefox 2.0 ed Internet Explorer 6.0