Komentarze w kodzie i dokumentacja kodu - narzędzie javadoc

 

Jeśli odpowiednio będziesz komentować swój kod w języku Java, będziesz mógł w każdej chwili użyć narzędzia javadoc, które służy do generowania dokumentacji kodu programu w oparciu o odpowiednio sformatowane komentarze.

 

Istnieją dwie metody komentowania wierszy kodu:

  • blok komentarza zaczynający się sekwencją /* i kończący się sekwencją */ - może obejmować wiele wierszy;
  • wiersz komentarza zaczynający się od sekwencji // - wszystko co występuje po dwóch ukośnikach w danym wierszu jest traktowane jako komentarz i nie jest uwzglęniane przez kompilator.

 

Przykładowy właściwie skomentowany kod programu w języku Java:

/**
 * This class represents devices used as computer monitor displays. 
 * @author    John Kowalski
 */
public class Screen {
    
    /**
     * Horizontal resolution of the screen - in pixels
     */ 
     private int width;   

    /**
     * Returns an Image object that can then be painted on the screen. 
     * The url argument must specify an absolute {@link URL}. The name
     * argument is a specifier that is relative to the url argument. 
     * <p>
     * This method always returns immediately, whether or not the 
     * image exists. When this applet attempts to draw the image on
     * the screen, the data will be loaded. The graphics primitives 
     * that draw the image will incrementally paint on the screen. 
     *
     * @param  url  an absolute URL giving the base location of the image
     * @param  name the location of the image, relative to the url argument
     * @return      the image at the specified URL
     * @see         Image
     */
     public Image getImage(URL url, String name) {    // This line is subject to change in the future
            try {
                return getImage(new URL(url, name));
            } catch (MalformedURLException e) {
                return null;
            }
     }
}

 

Lista dozwolonych tagów:

	 * @param argumenty Argumenty przekazane do programu podczas wywołania - w formie Stringów
	 * @author (classes and interfaces only, required)
	 * @version (classes and interfaces only, required. See footnote 1)
	 * @param (methods and constructors only)
	 * @return (methods only)
	 * @exception (@throws is a synonym added in Javadoc 1.2)
	 * @see Patrz także
	 * @since JDK 8
	 * @serial (or @serialField or @serialData)
	 * @deprecated Od jakiegoś czasu metoda przestarzała

Kompletny opis dozwolonych tagów javadoc oraz opis konwencji ich użycia w komentarzach jest dostępny tutaj:

http://www.oracle.com/technetwork/articles/java/index-137868.html

 

Uwaga:

Jeśli korzystasz z oprogramowania takiego jak Eclipse albo edytora Sublime Text z zainstalowaną wtyczką (plugin) DocBlockr, wystarczy przed nazwą atrybutu lub metody wpisać sekwencję /** i nacisnąć ENTER, aby automatycznie wygenerować blok komentarzy zgodny ze standardami javadoc dla danego atrybutu lub metody.

 

Pamiętaj, że dokumentacja kodu to cała obszerna struktura plików HTML i dlatego warto wygenerować ją w specjalnym katalogu/folderze - np. o nazwie "doc".

Nie trzeba takiego folderu tworzyć - wystarczy użyć opcji -d narzędzia javadoc.

 

Przykładowo, aby dla konkretnych plików Zoo.java oraz Animal.java utworzyć folder dokumentacji doc i wygenerować w nim pliki dokumentacji, użyj następującego polecenia w wierszu poleceń:

javadoc -d doc Zoo.java Animal.java

 

Możesz też wygenerować dokumentację dla wszystkich plików w bieżacym katalogu, używając polecenia
javadoc -d doc *.java

Możesz także wygenerować dokumentację dla bieżącego katalogu i wszystkich podkatalogów. Informacje na ten temat znajdziesz w dokumentacji narzędzia javadoc, a wiele przykładów użycia tego narzędzia znajdziesz w Internecie.

 

 

LAB: Klasyfikacja języków ze względu na paradygmat programowania