Autodoc


Nella notte dei tempi, quando il team primordiale lavorava alla stesura di un nuovo e rivoluzionario Sistema Operativo, che noi tutti conosciamo come AmigaOS, si presentò il problema di documentare, in modo uniforme, ciò che ciascun gruppo di lavoro stava realizzando.
Al geniale Bill Koester venne in mente una soluzione tanto banale quanto flessibile: il programmatore sa bene cosa fa, e come lo fa, la routine che sta scrivendo, quindi perchè non sfruttare i commenti che l'autore può (deve) inserire durante la sua stesura?
Detta così non sembra un'idea rivoluzionaria, però c'è dell'altro. Koester standardizzò i campi da inserire nei commenti.
Impose di inserirli in testa ad ogni procedura ed ogni campo rispondeva ad una ben determinata esigenza: nome della procedura, sintassi, ordine del passaggio dei parametri, quali registri coinvolge, il risultato, i possibili bug, un esempio di chiamata, le note, e le altre routine logicamente correlate.

Questo formato, fortunatamente, fu esteso sia al C che all'assembly e non fu una cosa difficile, in quanto tutta la struttura è vista da ogni traduttore come un unico commento che inizia con /*e termina con */.
Su Amiga quasi tutti i linguaggi di programmazione riconoscono questa sequenza come delimitazione di un commento, per questo motivo la tecnica degli Autodoc è applicabile virtualmente a qualunque linguaggio di programmazione.

Una volta terminata la stesura del programma e magari dopo averlo compilato, si passa lo stesso sorgente per un programma, il cui nome è autodoc, che estrapolerà tutti i commenti redatti nel formato riconosciuto, impaginandoli nel modo opportuno e riordinando alfabeticamente le routine presenti.
L'output del programma viene mandato direttamente sulla console, quindi normalmente viene visualizzato a video e perso. Però grazie alle proprietà di AmigaDOS di ridirigere gli output, lo si può archiviare in un file locale o mandarlo direttamente alla stampante o trasferirlo su un altro computer collegato in rete.
Autodoc accetta diversi parametri per attivare svariate funzioni durante la sua "pseudo-compilazione", la più importante delle quali è la realizzazione di un indice delle routine presenti.

Il sistema escogitato da Bill Koaster è stato così efficace da divenire il sistema ufficiale Commodore-Amiga per distribuire la documentazione agli sviluppatori registrati. Questi ultimi lo hanno accolto con tale entusiasmo da impiegarlo anche per i loro progetti.
Su altri sistemi la documentazione viene scritta da personale diverso dai programmatori, ed in tempi diversi: tutto ciò porta spesso ad imcoprensioni ed inesattezze nella documentazione ufficiale.
Dopotutto, a testimoniare la bontà e l'efficacia del sistema, può essere chiamato autodoc stesso: ancora oggi viene distribuito nella versione 1.0, ovvero quella originale scritta più di 15 anni fa!

Purtroppo autodoc fa parte del Native Developer Kit, che non correda la normale dotazione software di Amiga, ma solo quella destinata agli sviluppatori registrati. Può essere trovato sui cd della CATS distribuiti direttamente da Commodore-Amiga ai soli sviluppatori registrati, ma recentemente è stato reso disponibile sull'Amiga Developer CD 2.1, che chiunque può acquistare al modico costo di circa 60.000 lire, oppure lo si può trovare su una versione precedente dello stesso CD ad un costo quasi da realizzo.

Per sfruttare questa potenzialità nei propri sorgenti è necessario realizzare un commento come quello riportato di seguito, e che si riferisce ad un metodo della classe Clienti realizzato in linguaggio E.
Non preoccupatevi se non vi è chiara la procedura riportata sotto il commento: serve solo a dare un idea su come si procede durante la stesura del sorgente, mentre ciò su cui concentrare la vostra attenzione è il commento.

/****** Cliente/lunghezza()   ************************
*
*   NAME
*       lunghezza()
*
*   SYNOPSIS
*       my.lunghezza()
*
*   FUNCTION
*       Calcola la lunghezza effettiva, sommando le lunghezze dei singoli
*       campi, dell'oggetto indicato.
*
*   INPUTS
*       NESSUNO
*
*   RESULT
*       Restituisce la lunghezza in bytes dell'oggetto di tipo CLIENTE.
*
*   EXAMPLE
*       lunghezza := my.lunghezza()
*
*   NOTES
*       NESSUNA
*   BUGS
*       NESSUNO
*
*   SEE ALSO
*       NESSUNO
*
******************************************************************************
*
*/


PROC lunghezza() OF cliente

DEF lun=0

        lun := CL_NOME + CL_COGNOME + CL_VIA + CL_CAP + CL_LOCALITA
        lun := lun + CL_TELEFONO + CL_EMAIL + CL_DOCUMENTO + CL_NUMERO
        lun := lun + CL_CODSER + CL_CODBAR

ENDPROC lun

Un utile consiglio è di usare il taglia ed incolla, e poi procedere editando i contenuti delle singole voci.

Una volta salvato il sorgente è sufficiente aprire una shell AmigaDOS e battere il comando:

autodoc -C test.e


per vedere comparire a video il testo correttamente formattato. Volendo inserire anche l'indice delle routine è sufficiente aggiungere il parametro -I.

Una volta ottenuta la documentazione con un semplice redirect a file tipo:

autodoc -C test.e >ram:doc_test.txt


è facile trasformare questo testo in un file ipertestuale, magari in formato amigaguide, che rende ultra-rapida la consultazione della documentazione, oppure lo si può impaginare con un wordprocessor o DTP per poi stamparlo su carta.

Il miglior metodo per apprenderne il funzionamento è, come sempre in questi casi, provare ad usarlo, magari dopo aver dato una sbirciatina alla documentazione ufficiale, dove sono riportati tutti gli altri parametri accettati dal programma e con numerosi esempi di formattazione dei commenti.

Parafrasando uno showman foggiano in un noto spot d'annata: "Commentate gente, commentate...". :)


Francesco De Napoli