Sto usando Check-Style, FindBugs e PMD per convalidare il mio codice Java. Ho corretto quasi tutti i bug catturati da questi strumenti.Come aggiungere commenti a livello di pacchetto in Javadoc?
Non riesco a capire come scrivere "commento del pacchetto" che è un bug catturato da checkstyle. Ho esaminato la documentazione di Check-Style, ma non lo capisco.
Qualcuno potrebbe aiutarmi a scrivere un commento a livello di pacchetto in Java?
È necessario creare una paginaall'interno del pacchetto. Puoi leggere il contenuto e la struttura di questo file su How to Write Doc Comments for the Javadoc Tool page.
Utilizzando un file package.html per i commenti. Si prega di consultare questo documento: How to Write Doc Comments for the Javadoc Tool.
package-info.java nel pacchetto per documentareIl seguente collegamento fornisce ulteriori informazioni: http://docs.oracle.com/javase/specs/jls/se5.0/html/packages.html
si raccomanda che pacchetto -info.java, se presente, prendono il posto di package.html per javadoc e altri sistemi di generazione simili documentazione
pacchetto ampie annotazioni saranno dichiarati a package-info.java
Greetz, Ghad
Non ho mai sentito parlare di questo metodo prima. Puoi fornire un link a un documento che lo descrive? –
@Thomas Owens http://java.sun.com/docs/books/jls/third_edition/html/packages.html – emory
Compila il link: Si consiglia di prendere il pacchetto packageinfo.java, se presente. di package.html per javadoc e altri sistemi di generazione di documentazione simili. – GHad
Google ha trovato questo come il primo colpo:
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#packagecomments
Basta creare un file denominato package.html in ogni pacchetto.
I commenti javadoc a livello di pacchetto vengono inseriti in un file denominato package-info.java all'interno della directory del pacchetto. Contiene il commento e una dichiarazione del pacchetto:
/**
* Provides the classes necessary to create an applet and the classes an applet uses
* to communicate with its applet context.
* <p>
* The applet framework involves two entities:
* the applet and the applet context. An applet is an embeddable window (see the
* {@link java.awt.Panel} class) with a few extra methods that the applet context
* can use to initialize, start, and stop the applet.
*
* @since 1.0
* @see java.awt
*/
package java.lang.applet;
Questo è documentato qui: Package Comment Files
Interessante. La pagina sulla scrittura di commenti per Javadoc (vedi la mia risposta) non menziona nemmeno questo. –
@Thomas: mantenere sempre aggiornata la documentazione che si sovrappone è una cagna. –
In effetti lo è. Avrei sospettato che Sun (e ora Oracle) avrebbe fatto un lavoro migliore con il mantenimento della documentazione. Soprattutto da quando ho iniziato a sviluppare Java da oltre 5 anni e non ho mai visto o sentito parlare di questo metodo di produzione della documentazione a livello di pacchetto. –
È possibile aggiungere documentazione a livello di pacchetto.
Tipicamente package-info.java contiene solo una dichiarazione di package, preceduta immediatamente dalle annotazioni sulla confezione. Sebbene il file possa tecnicamente contenere il codice sorgente per una o più classi private del pacchetto, sarebbe una pessima forma.
Si consiglia che package-info.java, se presente, sostituisca il file package.html per javadoc e altri sistemi di generazione di documentazione simili.Se questo file è presente, lo strumento di generazione della documentazione dovrebbe cercare il commento della documentazione del pacchetto immediatamente prima della dichiarazione del pacchetto (eventualmente annotata) in package-info.java. In questo modo, package-info.java diventa l'unico repository per annotazioni e documentazione a livello di pacchetto. Se, in futuro, diventa desiderabile aggiungere altre informazioni a livello di pacchetto, questo file dovrebbe essere una comoda base per queste informazioni.
Ci sono due modi per aggiungere documentazione livello di pacchetto usando javadoc:
Maggiori dettagli ed esempi sono here. Quale usare: Javadoc: package.html or package-info.java
Perché il voto negativo? –
Suppongo che questo sia dovuto al fatto di non menzionare affatto package-info.java (che è la variante preferita al giorno d'oggi). –