Rozdział 7 - Metody - Dokumentowanie metod

Wiele nowoczesnych języków programowania udostępnia rodzaj komentarza, który możemy stosować w naszym kodzie do dokumentowania działania metod naszego programu. Komentarz taki zaczynamy od znaków /** a kończymy znakami */

Komentarze dokumentujące służą do:

• pomocy w zrozumieniu działania metody,
• opisie parametrów metody,
• opisie zwracanej wartości,
• informacji, czy metoda rzuca jakieś wyjątki i w jakich sytuacjach (o wyjątkach będziemy się uczyć wkrótce),
• dodatkowo, można w komentarzu poinformować o m. in. autorze metody i wersji, od której jest dostępna.

Istnieją narzędzia, które potrafią przejść przez kod źródłowy naszego programu i wygenerować do niego dokumentację na podstawie komentarzy tego specjalnego typu. Przykładem takiego narzędzia jest oficjalny program do tworzenia dokumentacji dla języka Java o nazwie JavaDoc.

Wygenerowaną w ten sposób dokumentację możemy zobaczyć na np. oficjalnej stronie dokumentacji języka Java pod adresem:

JavaDoc - Dokumentacja Java

Spójrzmy na przykład użycia tego rodzaju komentarzy:

import java.util.Scanner;

public class JavaDocPrzyklad {
  public static void main(String[] args) {
    System.out.println("Podaj liczbe");

    int x = getInt();

    System.out.println(
        "Ta liczba do kwadratu to " + policzKwadrat(x)
    );
  }

  /**
   * Metoda czeka na podanie przez uzytkownika wartosci,
   *  po czym ja zwraca.
   * @return Wartosc podana przez uzytkownika.
   */
  public static int getInt() {
    return new Scanner(System.in).nextInt();
  }

  /**
   * Zwraca przeslana liczbe podniesiona do kwadratu.

   * Przyklad: dla argumentu liczba rownego 5, zwroci 25.
   *
   * @param liczba Liczba, ktora chcemy podniesc do kwadratu.
   * @return Liczba podniesiona do kwadratu.
   */
  public static double policzKwadrat(int liczba) {
    return liczba * liczba;
  }
}

Przed metodami getInt oraz policzKwadrat znajdują się komentarze dokumentacyjne, opisujące co robi każda z tych metod. Dodatkowo, metoda policzKwadrat ma jeden argument, który opisujemy w następujący sposób: najpierw piszemy słowo param poprzedzone znakiem @ (małpa), po którym następuje nazwa argumentu, a po spacji jego opis (może on być dłuższy niż jedna linia).

Możemy w ten sposób opisać więcej, niż jeden parametr:

@param x Pozycja X.
@param y Pozycja Y.

Obie powyższe metody zwracają wartość – do opisu zwracanej wartości używamy słowa @return.

Pytanie: czy powinniśmy dokumentować wszystkie metody? Raczej nie – tylko te bardziej skomplikowane lub takie, których opis będzie przydatny w wygenerowanej dokumentacji, którą, być może, dostarczymy osobom, które będą korzystały z naszego kodu.