Javadoc

[parzi]

Semplice domanda..
Javadoc si usa per commentare solo package, classi e metodi o anche per spiegare il funzionamento di una riga di codice all'interno di un metodo?

Scusate la domanda banale.. Ma vorrei capire in maniera chiara... su internet spesso si contraddicono.. e non capisco..

Grazie mille

[andbin]

Originariamente inviato da parzi
Javadoc si usa per commentare solo package, classi e metodi o anche per spiegare il funzionamento di una riga di codice all'interno di un metodo?

No, solo classi (o interfacce, enum), costruttori, metodi, campi e anche package (in un modo un po' più particolare).

L'obiettivo della documentazione javadoc è quello di descrivere le specifiche di una certa API, non di raccontare cosa contiene e come funziona esattamente un pezzo di codice.

[parzi]

Quindi per il codice conviene mantenere i normali commenti // ?
o se il codice + è ben scritto non dovrebbero essere necessari?

[Naruto 92]

i commenti su singola linea o multilinea sono sempre ben accettati dagli sviluppatori che andranno a vedere il codice. non sono obbligatori però.

[parzi]

Una ulteriore informazione..
E' possibile ducumentare un actionPerformed? Ha senso?
In quanto ho provato facendo come un normale metodo ma non li prende...

[andbin]

Originariamente inviato da parzi
E' possibile ducumentare un actionPerformed? Ha senso?
In quanto ho provato facendo come un normale metodo ma non li prende...

Dipende come è stata dichiarata la classe che implementa il ActionListener. Come una anonymous inner class? O una inner class privata?

Dalla documentazione del tool javadoc:

The Javadoc tool parses the declarations and documentation comments in a set of Java source files and produces a corresponding set of HTML pages describing (by default) the public and protected classes, nested classes (but not anonymous inner classes), interfaces, constructors, methods, and fields.

[parzi]

L'ho implementato in questo modo...

finish.addActionListener(new ActionListener() {
				public void actionPerformed(ActionEvent event) {

[andbin]

Originariamente inviato da parzi
L'ho implementato in questo modo...

finish.addActionListener(new ActionListener() {
				public void actionPerformed(ActionEvent event) {

Appunto ... una "anonymous" class e come ho riportato prima: "but not anonymous inner classes".

Una anonymous class è "anonima" nel senso che il suo nome non è noto a priori (un nome a livello binario nel bytecode ovviamente ce l'ha, è generato dal compilatore). Insomma è una classe abbastanza nascosta e in tal caso che senso avrebbe documentare con javadoc una classe di cui appunto nessuno "sa" (o dovrebbe sapere) nulla??

Ribadisco quanto è già stato detto: se vuoi, per chiarezza del codice e per chi lo deve leggere (in futuro), sei libero di mettere tutti i commenti // e /* */ che ti pare in qualunque parte del sorgente.
La documentazione javadoc serve normalmente per documentare la API "pubblica" del software, e lo si fa tipicamente per una libreria, usata da altri.

[parzi]

Chiaro e gentile..

Grazie mille..

[parzi]

Non è che qualcuno mi può mostrare la sintassi corretta per commentare un package in javadoc?

Grazie mille..