JSDoc - javascriptowa dokumentacja

Opublikowany: 18.09.2011 18:34:50 | Komentarzy 3

Dlatego właśnie warto pisać dobrą dokumentację swojego kodu. Dzięki temu w przyszłości nam będzie łatwiej nanosić jakieś poprawki, analizować i edytować kod. Inni też będą mieli łatwiej z naszym kodem.

Inne języki programowania mają swoje standardy pisania dokumentacji np. JAVA JavaDoc. Dzięki nim, w łatwy sposób można wygenerować dokumentację np. do strony HTML. Podobnie jest w przypadku JS. Jest JSDoc. Składnia jest bardzo podobna do javowej.

JSDoc

JSDoc rozpoczyna się specjalnymi komentarzami /** */ w którym umieszczamy specjalne tagi:

@author

Informacje o autorze.

@constructor

Oznacza funkcję jako konstruktor.

@deprecated

Określa funckję jako depracated (przestarzała).

@exception

Synonim dla @throws

@param

Oznaczenie parametru funckji. Typ parametru określa się w nawiasach klamrowych {}.

@private

Prywatna funckja.

@return

Informacja o zwracanej wartości.

@see

Odwołanie się do innego miejsca w dokumentacji.

@this

Określenie typu parametru, który odwołuje się do funkcji.

@throws

Informacja o rzucanym wyjątku.

@version

Informacje o numerze (wersji) biblioteki.

Jak widać, nie ma tego dużo i są to podstawowe informacje, które mówią wszystko np. o danej funkcji.

Przykład JSDoc

Przykładowy komentarz JSDoc może wyglądać następująco:

/**
 * Oblicza pole koła.
 *
 * @param {Number} r Promień koła.
 * @return {Number} Pole koła.
 * @author Imię Nazwisko
 */
function liczbPoleKola(r) {
   return Math.PI*r*r;
}

Prawda, że ładnie i przede wszystkim profesjonalnie wygląda teraz nasz kod?

Skoro mamy już dobrze opisany kod, to teraz można wygenerować HTML.

Generowanie HTML dokumentacji

Jest kilka generotorów JSDoc. Jest jsdoc-toolkit, który nie jest już rozwijany. Jest JSDoc 3, dzięki którym można generować HTML z linii poleceń. Zaprezentuję Wam inne narzędzie do generowania HTML.

dox

Z racji tego, że mam zainstalowanego node.js, który prężnie się rozwija, pojawiło się też rozszerzenie, które parsuje pliki *.js do HTML z linii poleceń. Jest to dox. Aby wygenerować ładny kod trzeba wykonać linka kroków (w konsoli):

1. Pobieramy rozszenie dox: npm install dox
2. Parsujemy: dox --title Kolo kolo.js > kolo.html

Powyższa linijka "przetłumaczy" plik kolo.js do pliku kolo.html w wersji JSDoc.

Przykładowy plik wygenerowany przez JSDoc można zobaczyć tutaj.

Tagi: javadoc node dox node jsdoc node.js jsdoc node