Newsgroup: it.comp.os.linux.development
Titolo: tool per documentazione

Salve a tutti.
Mi trovo nella necessità di dover scegliere degli strumenti per
documentare un progetto software di una certa complessità. I linguaggi
utilizzati saranno java e/o php.
Dovrà essere documentato il codice e dovranno essere prodotti anche dei
manuali per lo sviluppatore, per l'amministratore, per l'utente,
ovviamente in vari formati.
Avevo pensato a docbook ma mi ponevo il problema di integrare la
documentazione nel codice: esistono strumenti per questi linguaggi di
programmazione che dalla documentazione inline del codice permettono di
estrarre docbook? quanto può essere facile/difficile integrare la
documentazione delle varie classi scritta nel codice con il resto?
Intendiamoci, quello che mi piacerebbe è semplicemente aggiungere un
capitolo docbook alla fine del manuale dello sviluppatore con tutta la
docuentazione delle classi, niente di più "interpolato".
Avete suggerimenti, consigli, esperienze?
Grazie
G.


doxygen, utilizza la stessa sintassi di javadoc, e puoi estrarre html, 
tek (quindi pdf) ed rtf, io utilizzo quello e funziona da dio, per php 
non l'ho mai utilizzato
Mirco



grazie, controllerò ma il mio problema era anche come integrare questa
parte "automatizzata" con la parte scritta in docbook "a mano".

 mano".
  Io dico la mia, magari poi sei libero di mandarmi ``in /dev/null'' :-)
  Io mi son creato un sistema SGML da zero; la dtd l'ho chiamata PLML;
  è abbastanza minimale, il sezionamento del testo è il più possibile
  intuitivo e praticamente i nomi delle sezioni sono copiati dalle classi
  LaTeX standard. L'output è nei formati TXT HTML mono e multipagina,
  TEX (PS, PDF, DVI) altri da venire.
  Siccome poi io stesso mi rompevo le scatole di scrivere con le TAG
  <SGML> ho creato anche una sovra-struttura con notazione    
  extra-semplificata, liberamente ispirata a *nroff, ma di tipo logico 
  e non tipografico. Un documento minimale ha l'aspetto seguente:
 --------------------------------------8<--------------------
.a Il mio primo articolo | Nome autore
.s prima sezione 
bla bla bla
.ss prima sotto- sezione 
bla bla bla
bla bla bla
 --------------------------------------8<--------------------
E la sua espansione in SGML è come di seguito:
 --------------------------------------8<--------------------
<!DOCTYPE plml SYSTEM
[
<!-- Spazio per entità personalizzate -->
]>
<ARTICLE title=" Il mio primo articolo " author=" Nome autore">
<SECTION name=" prima sezione">
bla bla bla
<SUBSECTION name=" prima sotto- sezione">
bla bla bla
bla bla bla
</SUBSECTION></SECTION></ARTICLE>
 --------------------------------------8<--------------------
 Se vuoi maggiori info, la pagina dove trovi un po' tutto (GPL) è
 la seguente:  
 
http://www.lulli.net/cgi-bin/oz.pl?hack
 Magari a te non serve a nulla, ma tutto 'sto casino permette anche 
 di inserire codice TeX tipo formule, grafici con MetaPost e 
 quant'altro... fornendo un output sia in TeX che PNG, tramite 
 imagemagick  e strani altri trucchi ... :-)
 Ciao,
 Paolo
-- 
<!--_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
                      The Hacking Pages
 
www.lulli.net
-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-->