Quale sarebbe una buona alternativa alla documentazione in linea Java, cioè si può avere un file docs separato in qualche modo mappato su un file sorgente java?
Non mi sono mai piaciute le sezioni di commenti enormi disseminate nel codice.
Utilizzo la funzionalità Javadoc di commenti del pacchetto per evitare littering codice sorgente con commenti verbosi sulla documentazione:
Package-Level Comments
With Javadoc 1.2, package-level doc comments are available. Each package can have its own package-level doc comment source file that The Javadoc tool will merge into the documentation that it produces. This file is named
package.html(and is same name for all packages). This file is kept in the source directory along with all the*.javafiles. (Do not put thepackages.htmlfile in the new doc-files source directory, because those files are only copied to the destination and are not processed.)The file package.html is an example of a package-level source file for
java.textand package-summary.html is the file that the Javadoc tool generates.The Javadoc tool processes
package.htmlby doing three things...
Usando la funzione precedente, avevo una dettagliata documentazione dettagliata per classi e metodi nel pacchetto memorizzato separatamente del codice, in un file html dedicato. Per quanto riguarda i commenti Javadoc nei file java, ho appena scritto brevi spiegazioni, aggiungendo del testo come
If needed, refer to package documentation for more details.
Una cosa che mi è particolarmente piaciuta è che sebbene i documenti fossero nel file separato e in un formato più conveniente per documenti di grandi dimensioni (html), è stato archiviato abbastanza vicino al codice sorgente correlato e tutti gli aggiornamenti in esso contenuti erano automaticamente raccolto durante la compilazione.
A partire da Java 1.5 , puoi in alternativa mettere un package-info.java insieme alle classi del pacchetto. Questo file dovrebbe assomigliare a questo:
/**
* Javadoc for your package here
*/
package com.yourpackage;
la documentazione JLS suggerisce che questo è il modo preferito:
The following scheme is strongly recommended for file-system-based implementations: The sole annotated package declaration, if it exists, is placed in a source file called
package-info.javain the directory containing the source files for the package...It is recommended that
package-info.java, if it is present, take the place ofpackage.htmlfor javadoc and other similar documentation generation systems. If this file is present, the documentation generation tool should look for the package documentation comment immediately preceding the (possibly annotated) package declaration in package-info.java. In this way,package-info.javabecomes the sole repository for package-level annotations and documentation. If, in future, it becomes desirable to add any other package-level information, this file should prove a convenient home for this information.
Leggi altre domande sui tag java documentation javadocs