Java >> Programma Java >  >> JDK

Tag Javadoc di riepilogo di JDK 10

JDK

JDK 10 introduce un tag Javadoc {@summary} tramite il numero JDK-8173425 ("Javadoc ha bisogno di un nuovo tag per specificare il riepilogo."). Questo nuovo tag consente allo sviluppatore di specificare esplicitamente quale parte del commento Javadoc appare nel "riassunto" piuttosto che fare affidamento sul trattamento predefinito di Javadoc alla ricerca di un punto e di uno spazio per delimitare la fine della parte di riepilogo del commento. JDK-8173425 afferma:"Attualmente in javadoc il riepilogo (prima frase) di un elemento viene decifrato da una regola punto-spazio o, se necessario, utilizzando BreakIterator". Aggiunge che può essere fonte di confusione sapere quale sarà quella frase riassuntiva implicitamente selezionata.

Il modo più semplice per vedere {@summary} in azione può essere tramite esempi Javadoc. L'elenco di codice successivo mostra quattro metodi con commenti Javadoc simili, due che utilizzano {@summary} esplicito tag e due che si basano sulla costruzione di riepilogo Javadoc implicita.

Dimostrazione di {@summary} nei commenti sul metodo Javadoc 

package dustin.examples.javadoc;

/**
 * Demonstrate JDK 10 added summary support. Demonstrates
 * this by comparing similar methods' Javadoc comments with
 * and without use of new "@summary" tag.
 */
public class Summary
{
   /**
    * This method's first sentence is normally in the summary.
    * Here are some of its characteristics:
    * <ul>
    * <li>This method does great things.</li>
    * <li>This method does not really do anything.</li>
    * </ul>
    */
   public void implicitSummary1()
   {
   }

   /**
    * This method's first sentence is normally in the summary.Here are some of its characteristics:
    * <ul>
    * <li>This method does great things.</li>
    * <li>This method does not really do anything.</li>
    * </ul>
    */
   public void implicitSummary2()
   {
   }

   /**
    * {@summary This method's first sentence is normally in the summary.
    * Here are some of its characteristics:
    * <ul>
    * <li>This method does great things.</li>
    * <li>This method does not really do anything.</li>
    * </ul>}
    */
   public void explicitSummary1()
   {
   }

   /**
    * {@summary This method's first sentence is normally in the summary.Here are some of its characteristics:
    * <ul>
    * <li>This method does great things.</li>
    * <li>This method does not really do anything.</li>
    * </ul>}
    */
   public void explicitSummary2()
   {
   }
}

Quando lo strumento Javadoc fornito con la prima Release Candidate JDK 10 (18.3) (Build 43) viene eseguito su questa semplice classe, il "Riepilogo metodo ” dell'HTML generato appare come segue in un browser web.

Confrontando l'output HTML con il codice Java commentato sopra, viene mostrato come il {@summary} consente un controllo esplicito di ciò che appare nei riepiloghi dei metodi.

Etichetta Java