Decl -- Dichiarazioni

Come abbiamo visto uno o più tag principali possono includere nel proprio ambito un blocco di codice. Si tratta ovviamente del codice utilizzato per implementare l'entità descritta. Questo codice può ricevere due trattamenti:

1. Viene incluso nel documento a rafforzarne il contenuto.
2. Viene parsato per estrarne le dichiarazioni che verranno incorporate nel documento tramite dtd Decl.

Tramite opportuni tag è possibile chiedere al sistema di parsare il codice al fine di estrarre dirrettamente dal codice la documentazione di dettaglio. Il parser esamina sia il codice vero e proprio che i commenti che lo accompagnano e genera una struttura Decl che viene incorporata nel documento. Si devono tener presente diversi problemi:

1. Il parser non è in grado di gestire qualunque codice: è dunque necessario poter scegliere quale codice viene dato in pasto al parser.
2. In alcuni casi il parser tratta dei costrutti che non esistono nel linguaggio C. In questo caso il parser deve trattare come codice quello che il compilatore considera un commento.

Il tag @Decl viene utilizzato per scegliere il codice che viene dato in pasto al parser. Tramite questi tag si costruisce un sorgente che viene esaminato dal parser. Questo sorgente viene costruito da frammenti di codice, commenti trattati come codice. Ciascun frammento è compreso tra un tag @Decl e la sua chiusura @/Decl.

Il testo riportato in seguito mostra la documentazione di un set di costanti. Il testo definisce due blocchi di codice:

1. Il primo blocco comprende:
1. Un zona commento che verrà ignorata dal parser.
2. La dichiarazione 'C' dell'enumerazione EnAppClass. Dovrebbe risultare apparente come i commenti che accompagnano l'enumerazione vengono associati ai singoli elmenti.
2. Il secondo blocco comprende:
1. Una dichiarazzione kondefine che verrà ignorata dal compilatore ma trattata dal parser.
2. Un elenco di define con relativi commenti che verrà trattato sia dal compilatore che dal parser.
3. La chiusura della dichiarazione kondefine che verrà trattata solo dal parser.

/**
@Kon     Sample :: kAll : All Declarations
@Descr   <P>This files tests all possible source code constant declarations.</P>
@/Descr
**/
/* @Decl */
/**
    Costanti Varie
**/
enum EnAppClass                 // Class of Application
                                /* Defines the application class */
  {
  kUnknwnAppClass      =  0,    // Undefined 
  kCStandardAppClass   =  1,    // Standard C   Program (unsupported)
    ....
  kArGuiAppClass       = 15     // AR GUI   C++ Program
  };
/* @/Decl */
/* @Decl
kondefine EnArPgmType           // Ar Programmer Type
    {
*/
#define kArPgmNull    0         // Non definito
#define kArPgmIdiot   'I'       // Idiota
#define kArPgmAverage 'A'       // Normale
#define kArPgmSmart   'S'       // Furbo
/*
    };
/* @/Decl */
/* @/Kon */

Il parser esaminerà un testo estratto sulla base dei comandi @Decl che riportiamo qui in seguito.

/**
    Costanti Varie
**/
enum EnAppClass                 // Class of Application
                                /* Defines the application class */
  {
  kUnknwnAppClass      =  0,    // Undefined 
  kCStandardAppClass   =  1,    // Standard C   Program (unsupported)
    ....
  kArGuiAppClass       = 15     // AR GUI   C++ Program
  };
kondefine EnArPgmType           // Ar Programmer Type
    {
    #define kArPgmNull    0         // Non definito
    #define kArPgmIdiot   'I'       // Idiota
    #define kArPgmAverage 'A'       // Normale
    #define kArPgmSmart   'S'       // Furbo
    };

Il parser esamina il testo scartando i commenti al primo livello, e trattando tutte le entità definite, inclusa la dichiarazione kondefine che non appartiene al 'C' ma viene gestita dal parser.

Avendo definito come alimentare il parser esaminaimo in dettaglio tipi di dichiarazione che gestisce:

1. Enumerazioni.
2. External.
3. Group.
4. Strutture e Union.
5. Typedef.