[JAVA] Descrizione di una funzione con JavaDoc

[bako]

Stavo scrivendo la javadoc. mi sono sorti dei dubbi.
Nella descrizione della funzione si mette cosa fa (breve descrizione) o anche come fa (passo per passo)?
i commenti della classe tipo:

if (a=b)
   b++ //incrementa b
else 
  a++ //incrementa a

vanno messi nella javadoc o lasciati lì?

[andbin]

Originariamente inviato da bako
Stavo scrivendo la javadoc. mi sono sorti dei dubbi.
Nella descrizione della funzione si mette cosa fa (breve descrizione) o anche come fa (passo per passo)?
i commenti della classe tipo:

if (a=b)
   b++ //incrementa b
else 
  a++ //incrementa a

vanno messi nella javadoc o lasciati lì?

I commenti come quelli che hai appena indicato ( // ), non vengono presi in considerazione da Javadoc.
In generale, Javadoc prende in considerazione solo i commenti speciali /** .... */ relativi alle dichiarazioni di classi, interfacce, metodi, costruttori o variabili di classe/istanza.

[bako]

si lo so.
la mia domanda era un'altra. Per scrivere una javadoc "corretta", è bene inserire quei commenti? dove?

[andbin]

Originariamente inviato da bako
si lo so.
la mia domanda era un'altra. Per scrivere una javadoc "corretta", è bene inserire quei commenti? dove?

Cosa intendi per javadoc "corretta"???
Come ho detto prima, si usa il commento speciale /** ... */ per Javadoc e dentro ci devi mettere la documentazione (che può utilizzare i tag HTML) e anche i tag @xxx riconosciuti da Javadoc per i parametri, il valore di ritorno, ecc....

Poi all'interno del codice puoi mettere tutti i commenti /* */ e // che vuoi, che non vengono presi in considerazione da Javadoc.

[Andrea1979]

A meno che non ci siano diatribe in corso su qualcuna delle tecniche utilizzate per ottenere cosa in un metodo, il commentare passo passo è abbastanza male nella compilazione di un javadoc, imho. Non stai presentando l'esamino all'università... gli utenti normali vogliono sapere che cosa fa il metodo, non tanto come lo fa. Salvo appunto qualche caso particolare.

Se hai i sorgenti di java, guardati un po' i commenti javadoc-ready che trovi nelle varie classi e prendi spunto.

[bako]

Originariamente inviato da Andrea1979
A meno che non ci siano diatribe in corso su qualcuna delle tecniche utilizzate per ottenere cosa in un metodo, il commentare passo passo è abbastanza male nella compilazione di un javadoc, imho.Non stai presentando l'esamino all'università... gli utenti normali vogliono sapere che cosa fa il metodo, non tanto come lo fa. Salvo appunto qualche caso particolare.

Se hai i sorgenti di java, guardati un po' i commenti javadoc-ready che trovi nelle varie classi e prendi spunto.

in verità sì..