Creazione di un oggetto

Sezione in fase di stesura...

Documentazione degli oggetti

Per la documentazione degli oggetti si devono seguire delle linee guida molto simili alle regole per la documentazione del codice C#. La sintassi per la documentazione è composta linee di commento che iniziano con la sequenza di 3 caratteri apice

'''

All'interno di questi commenti dovranno essere inseriti i blocchi identificati descritti di seguito.

Blocchi generici

Blocco	Descrizione
<maindoc>...</maindoc>	Blocco entro il quale sarà presente la descrizione principale dell'oggetto
<nodoc>...</nodoc>	Blocco per l'esclusione del codice dalla documentazione

Blocco <maindoc>

All'interno di questo blocco dovrà essere inserita la descrizione principale dell'oggetto,che poi verrà visualizzata all'inizio della pagina della documentazione dell'oggetto. All'interno di questa descrizione la sintassi potrà contenere sia la sintassi HTML che la sintassi MARKDOWN. Un esempio di utilizzo è il seguente:

'''<maindoc>
'''<b>Documentazione Principale</b>
'''...
'''</maindoc>

Blocco <nodoc>

Tutto il codice entro questo blocco non verrà preso in considerazione per la documentazione. Può essere utile per escludere delle funzioni che non hanno bisogno di essere documentate o che devono rimanere nascoste Un esempio di utilizzo è il seguente:

'''<nodoc>
...
function test1(a as int) as int
   a = a + 1
   test1 = a
endfunction
 
function test2(b as int) as int
   b = b + 1
   test2 = b
endfunction
...
'''</nodoc>

Blocchi per la documentazione delle funzioni

Blocco	Descrizione
<summary>...</summary>	Blocco per l'inserimento delle descrizione della funzione
<param>...</param>	Blocco per la descrizione di un parametro della funzione. In questo blocco ci deve essere l'attributo name che conterrà il nome del parametro da documentare
<return>...</return>	Blocco per la descrizione del dato restituito dalla funzione
<remarks>...</remarks>	Blocco per l'inserimento delle osservazioni aggiuntive per la funzione
<example>...</example>	Blocco per l'inserimento di un codice di esempio per la descrizione della funzione

I blocchi descritti nella tabella devono essere inseriti appena prima della funzione da documentare, e conterranno tutte le definizioni che verranno inserite nella documentazione. Un esempio della documentazione è il seguente:

'''<summary>
'''Scrittura singola variabile
'''</summary>
'''<param name="nodo">Nodo dello slave</param>
'''<param name="addr">Indirizzo dell'area di memoria dello slave</param>
'''<param name="value">Valore da impostare</param>
'''<return>ritorna 0=0k, >0 errore</return>
'''<remarks>Scrive una singola variabile al nodo passato
'''</remarks>
'''<example>
'''  ...
'''  obj.write_reg(1, 12, 11)
'''  ...
'''</example>
function ?p1?.write_reg(nodo as char, addr as uint, value as int) as char
...
endfunction