Doxygen vs Javadoc [chiuso]

Question

Ho appena capito da un articolo su CACM che Doxygen funziona anche con Java (e molti altri linguaggi). Ma Java ha già lo strumento Javadoc. Qualcuno può spiegare quali sono i pro e i contro di entrambi gli approcci? Si escludono a vicenda? Esiste un plug-in Maven per Doxygen?

Answer 1

Doxygen ha una serie di funzioni che JavaDoc non offre, ad es. i diagrammi di classe per le gerarchie e il contesto di cooperazione, più pagine di riepilogo, esplorazione del codice sorgente opzionale (reticolato con la documentazione), supporto di tag aggiuntivi come @todo su una pagina separata e può generare output in formato TeX e PDF . Permette anche molta personalizzazione visiva.

Poiché Doxygen supporta i tag JavaDoc standard, è possibile eseguire Doxygen su qualsiasi codice sorgente con commenti JavaDoc su di esso. Spesso può anche avere senso eseguire il codice sorgente senza JavaDoc poiché i diagrammi e la navigazione del codice sorgente possono aiutare a comprendere il codice anche senza la documentazione. E poiché lo strumento JavaDoc ignora i tag sconosciuti, puoi persino utilizzare tag Doxygen aggiuntivi senza interrompere la generazione JavaDoc.

Detto questo, devo ammettere che non uso Doxygen da molto tempo. Tendo ad affidarmi molto al mio IDE al giorno d'oggi per fornire la stessa visualizzazione e di solito non leggo JavaDoc come pagine HTML ma importare i file di origine nel mio IDE in modo che possa generare flyout JavaDoc e posso saltare alle definizioni. È ancora più potente di quello che Doxygen ha da offrire. Se vuoi avere documentazione al di fuori dell'IDE e sei felice di eseguire strumenti non Java, allora Doxygen vale la pena provare poiché non richiede alcuna modifica al tuo codice Java.

Answer 2

Userei Doxygen con Java solo se non conosci Java e hai già usato Doxygen, riducendo la curva di apprendimento che sperimenteresti con javadoc. Se non hai mai usato Doxygen, mi limiterei a utilizzare javadoc, dato che è stato progettato appositamente per Java. Se non conosci nessuno dei due e lavori in C ++ (o in altre lingue supportate) tanto quanto Java, Doxygen è una buona scelta, dato che sarai in grado di usarlo per entrambe le lingue.

Entrambi gli strumenti sono facili da usare, con un set di funzioni simili. Entrambi hanno plugin (o sono pre-integrati) per NetBeans ed Eclipse che rendono ancora più veloce la generazione di documenti. Esistono molte sovrapposizioni nello stile di commento usato da ciascuno, ma non sono esattamente uguali, quindi sarebbe difficile mescolarle insieme (dovresti conoscere i dettagli di < em> both , tralasciando tutte le funzionalità specifiche dell'una o dell'altra). Non l'ho mai usato, ma sembra che ci sia un plugin Maven per Doxygen .

Answer 3

Mi piace il fatto che con Doxygen sia possibile visualizzare i diagrammi di classe nella stessa pagina della documentazione. Inoltre, mi piace il fatto che ti colleghi direttamente al codice sorgente, se necessario. Non sono a conoscenza del fatto che javadoc abbia queste funzionalità.

Answer 4

Un grande vantaggio di JavaDocs è che funzionano e basta. Tutto ciò che è necessario per crearli e visualizzarli è incluso nel JDK che è già necessario aver installato per compilare i programmi.

Doxygen, d'altra parte, può essere una seccatura da configurare e far funzionare correttamente. ma se impostato correttamente dovrebbe essere in grado di generare PDF, RTF e DocBooks, nonché HTML. L'HTML non è organizzato per impostazione predefinita come JavaDocs poiché index.html porta in primo piano una pagina vuota. Inoltre, le classi inline e i membri statici potrebbero aver bisogno di flag speciali da includere nella documentazione e se vuoi generare un PDF potresti dover affrontare i problemi della tua distribuzione di Linux che non hanno il comando pdflatex necessario (ad esempio Ubuntu / Mint hanno avuto problemi di recente), quindi se dovessi semplicemente installarlo ed eseguirlo, potresti ottenere una schermata piena di errori anche con un semplice programma. Rispetto alla facilità di ottenere javadoc automaticamente quando si installa l'API, l'installazione di Doxygen può essere un'esperienza infelice. Una volta superati gli ostacoli, dovrebbe essere più flessibile nel gestire progetti che coinvolgono più di un semplice java.