wiki:JavaDdoc
Last modified 10 years ago Last modified on 2008-01-27 16:15:13

JavaDoc ja Ohjelmointi 2 -kurssi

Kurssilla jokainen metodia ja luokka on dokumentoivat käyttäen JavaDocia?.

Käyttö

Tämä tarkoittaa sitä, että metodit kommentoidaan kertoen metodin tehtävä, paramterit ja mahdollinen paluuarvo sekä poikkeukset muodossa:

 /**
   * Poistaa merkkijonosta jono kaikki jonon mita esiintymät.
   * <pre>
   *  jono   poistettava       tulos
   * Catcat      at      =>    Cc
   * Paatti      at      =>    Pi
   * Puatit      at      =>    Puit
   * </pre>
   * @param jono merkkijono josta poistetaan
   * @param poistettava jono, jonka esiintymää ei saa olla tuloksessa
   * @return jono jossa ei ole yhtään poistettava-jonon esiintymää
   * @since 1.4
   */
  public static String poista(String jono, String poistettava) {

Eclipsesllä JavaDoc kommentoinnin pohja syntyy helposti, kun menee metodin nimen yläpuolelle ja kirjoittaa /:

 /**
  public static String poista(String jono, String poistettava) {

Nyt kun painaa Return / perässä, Eclipse täydentää dokumentoinnin rungon:

 /**
   * 
   * @param jono
   * @param poistettava
   * @return
   */
  public static String poista(String jono, String poistettava) {

Tähän on helppo lisätä parametrien ja paluuarvon merkitys ja metodin tehtävät. Kommentteja EI SAA jättää tuohon muotoon vaan ne on todella täydennettävä.

Puuttuvista kommenteista virheitä

Kannattaa asettaa itselleen Eclipse niin, että se varoittaa puuttuvista ja vääränmuotoisista kommenteista:

  • Window/Preferences/Java/Compiler/JavaDoc?
  • Muuta asetukset seuraavasti:
      [X] Process Javadoc comments
      Malformed Javadoc comments: Error
      Only consider members as visible as: Protected
      [X] Report errors in tags
      [X] Report non visible References
      Missing Javadoc tags: Warning
      Only consider members as visible as: Protected
      [X] Check overrding and implementing methods
      Missing Javadoc comments: Warning
      Only consider members as visible as: Protected
      [X] Check overrding and implementing methods