Newsgroup: it.comp.lang.c++
Titolo: Documentare libreria C++

Devo iniziare a scrivere la documentazione di una libreria in C++ che 
sto scrivendo, usualmente uso doxygen, ma questa libreria e` un po` 
particolare in quanto composta di soli header, ho paura che se usassi 
doxygen (in cui la documentazione si scrive negli header o nei sorgenti) 
triplicherei o peggio il peso della libreria aumentando di conseguenza i 
tempi di compilazione dei sorgenti.
Speravo ci fosse un tool che analizzando gli header produce un template 
con nomi di classi e member function da riempire + o - a mano. Googlare 
non mi ha pero` dato link utili...
Anche metodi alternativi sono bene accetti!
Bye,
  Gabry

 tempi di compilazione dei sorgenti.
Guarda, io non ho mai programmato un compilatore, ma sono abbastanza
sicuro che i commenti vengano semplicemente rimossi dal preprocessore.
Il compilatore non li vedrą mai.
Direi che potresti fare un test scrivendo una valanga di commenti del tipo:
/**
 * Pippo pippo pippo
 * Pippo pippo pippo
 * Pippo pippo pippo
 * Pippo pippo pippo
 * Pippo pippo pippo
 * Pippo pippo pippo
 * ...
 * Pippo pippo pippo
 */
void foo();
E vedere se la compilazione rallenta (secondo me no, ma non sono
un'autoritą...).
Perņ puoi benissimo mettere la documentazione in un file parallelo, e
usare la notazione di Doxygen per la documentazione in posti non standard:
/** \fn void foo()
 * Pippo pippo
 * Topolino Minni
 */
Ciao,
- -Federico
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (GNU/Linux)
Comment: Using GnuPG with SUSE - 
http://enigmail.mozdev.org
iD8DBQFIaNn6BIpu+y7DlLcRAnPYAJ9X7QsTykceqw99hIodrtw3mc9KEACdHuuP
5IPGk+eCzeqN6Tki38PXBnA=
=xoG+
-----END PGP SIGNATURE-----

 tempi di compilazione dei sorgenti.
Guarda, io non ho mai programmato un compilatore, ma sono abbastanza


 tempi di compilazione dei sorgenti.
Guarda, io non ho mai programmato un compilatore, ma sono abbastanza


 Il compilatore non li vedrà mai.
Non e' detto che siano due programmi distinti e comunque il tempo di
preelaborazione si somma a quello della compilazione vera e propria.
Detto questo hai ragione nel senso che la rimozione dei commenti e'
una delle prime fasi della compilazione.
Probabilmente un elevata quantita' di commenti non ha costo zero,
visto che l'analisi lessicale e' considerata una parte relativamente
pesante della compilazione. E' pero' vero che oggi come oggi penso che
la maggior parte dei compilatori si legga i file in memoria in blocco
e qualche kilobyte di commenti in piu' non fa una grande differenza.
A maggior ragione se la libreria in questione contiene molti template
complessi, nel qual caso penso che il peso dei commenti diventi del
tutto trascurabile. Meglio davvero provare, pero'.
Ciao,
Nicola

 tutto trascurabile. Meglio davvero provare, pero'.
Si, la libreria e` particolare in quanto e` header only, in totale circa 
6000 linee senza la documentazione, ed e` ancora incompleta.
Comunque al momento prendero` la strada del classico stile inline di 
documentazione, riservandomi magari in un 2o tempo a libreria finita di 
fare uno script che toglie tutti i commenti di documentazione 
(probabilmente c'e' gia` qualcosa, in ogni caso e` un task molto 
semplice, iniziano per /** o ///)
Bye,
  Gabry

 si moltiplicheranno anche.
Un approccio che potrebbe servire a mantenere un minimo di
leggibilita' e' mettere nei .h/.hpp solo le definizioni delle classi,
corredate dei relativi commenti. L'implementazione delle funzioni
inline/template andrebbe invece messa in file .ipp, corredati anche
questi degli opportuni commenti. Ovviamente ogni .h/.hpp includerebbe
il .ipp corrispondente.
In alcuni casi si puo' persino riuscire a includere selettivamente
i .ipp, in funzione dell'effettiva necessita' da parte del compilatore
di istanziare il relativo contenuto. La gestione ovviamente si
complica.
Un giorno avremo i moduli e tutto questo perdera' di senso.
Ciao,
Nicola

 Un giorno avremo i moduli e tutto questo perdera' di senso.
e' una feature pianificata x il C++ 0x o si dovranno aspettare altri 10 
anni? :)
Bye,
  Gabry

On Jul 1, 2:57 pm, Gabriele Greco

No, successiva. Il piano sarebbe di avere la versione dell standard
successiva a C++ 0x (che uscira' presumibilmente nel 2010 per tempi
tecnici) dopo 4-5 anni, pero'...
Ciao,
Nicola

Gabriele Greco ha scritto:

Ho paura sia una feature programmata per il c++xx :)
(a parte che purtroppo sembra che per poter fare davvero il C++0x siano 
costretti a contare in esadecimale: c++0A o c++0B .... forse sarebbe il 
caso di incominciare più realisticamente a parlare di c++1X....)
GM