Lyhyt Javadoc-ohje

Tämä dokumentti on lyhyt ohjeistus Sun Microsystemsin Javadoc-työkalun käytöstä Java-luokkien kommentoinnissa.

Tämän dokumentin lisäksi Javadoc-ohjeita löytyy esimerkiksi sivuilta

• How to Write Doc Comments for Javadoc
• Requirements for Writing API Specifications

Huomioita

• Javadoc-kommentti alkaa merkkijonolla /** ja päättyy merkkijonoon */, esim.

       /**
        * Konstruktori.
        */
       public Luokka() {
       }
  

• Kirjoita ensimmäinen lause lyhyenä yhteenvetona metodista, koska Javadoc sijoittaa sen automaattisesti Method Summary -tauluun ja hakemistoon.
• Javadoc-kommenteissa -- eli käytännössä luokkien ja metodien kuvauksissa -- voi käyttää perinteisiä HTML-tagejä asioiden esittämiseen, koska Javadoc-työkalu muodostaa kommenteista tavallisia HTML-sivuja.
• Jätä yksi rivi metodin kuvauksen ja tagien väliin. Esim.

      /**
       * Kertoo <code>eka</code>n <code>toka</code>lla ja palauttaa näiden
       * tulon.
       *
       * @param eka kerrottava.
       * @param toka kertoja.
       * @return <code>eka</code>n ja <code>toka</code>n tulon.
       */
      public int kerro(int eka, int toka) {
          return eka * toka;
      }
  

Esimerkkejä

Tiedostossa Luokka.java on esimerkki Javadocin käytöstä Java-luokan dokumentoinnissa ja kommentoinnissa. Katso myös vastaava API-dokumentti.