Logo

Blog o JavaScript, jQuery, HTML5, CSS3 i 4. Porady jak pisać dobrej jakości kod, tutoriale, nowości.

JSDoc - javascriptowa dokumentacja

Kiedy tworzymy kod, można to robić na kilka sposobów. Można pisać byle jak, można pisać samokomentujący się kod, a można też pisać komentarze. O ile w przypadku jednosobowych projektów analiza kodu nie sprawia problemów, to o ile przy większych projektach z większą ilością osób, ogarnięcie całego kodu nie jest takie proste.

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.

Autor wpisu

Piotr cichosz (shpyo) — Front-end developer Twórca kilku serwisów internetowych oraz autor kilku blogów. Pasjonat nowych, otwartych technologii.

Komentarze

Gavatar procek

18.09.2011 procek

Nie wiem czy myślimy o tym samym, ale czy istnieje jakiś pomost dzięki któremu można użyć Doxygena?

Gavatar shpyo

21.09.2011 shpyo

@procek: obawiam się, że nie będę mógł Ci pomóc.

Gavatar atlantic mariner

22.09.2011 atlantic mariner

Właśnie na takie posty czekałem. Java script bez zbędnej ściemy i przybierania w piękne słowa. Pozdrawiam !

Dodaj komentarz