ESDoc – Generowanie dokumentacji JS/JavaScript

Na końcu projektu nikomu nie chce się już pisać dokumentacji, a często jest to konieczne. Nie zawsze od początku o tym pamiętamy, ewentualnie pamiętamy, ale myślimy że później ją stworzymy. Przecież teraz to „ja muszę kodować”. Jednak dzięki narzędziom automatycznego generowania dokumentacji możemy tego żmudnego zajęcia uniknąć, ale tylko jeśli od początku będziemy o tym pamiętać. Wtedy dokumentacja będzie zawsze na zawołanie. Generowanie dokumentacji JS może być bardzo proste między innymi dzięki narzędziu ESDoc. Użyłem go w projekcie opartym o framework Aurelia.io, gdzie bardzo dobrze się sprawdził.

Generowanie dokumentacji JS z użyciem ESDoc

Generowanie dokumentacji JS narzędziem ESDoc jest banalnie proste i szybkie. Zakładając, że mamy zainstalowany NPM, to dodanie tego narzędzia do projektu sprowadza się do wykonania kilku komend w konsoli (Mac/Linux):

instalacja globalnie ESDoc przez npm:

npm install -g esdoc

przejście do katalogu z projektem:

cd your-project/

stworzenie pliku z konfiguracją esdoc:

echo '{"source": "./src", "destination": "./doc"}' > .esdoc.json

wygenerowanie dokumentacji przez uruchomienie ESDoc:

esdoc

otwarcie dokumentacji w przeglądarce:

open ./doc/index.html

W przypadku mojego projektu opartego na Aurelii, musiałem dodać w pliku konfiguracyjnym .esdoc.json obsługę nowej składni ECMAScript:

{
"source": "./src",
"destination": "./doc",
"experimentalProposal": {
    "classProperties": true,
    "objectRestSpread": true,
    "decorators": true,
    "doExpressions": true,
    "functionBind": true,
    "asyncGenerators": true,
    "exportExtensions": true,
    "dynamicImport": true
  },
"coverage": true
}

Zmienną coverage możemy kontrolować, czy dodatkowo ESDoc ma sprawdzać ile procent kodu jest opisane przez dokumentację. Może to zachęcać do uzupełniania dokumentacji.

Po odpaleniu w konsoli komendy esdoc dokumentacja zostanie wygenerowana tylko na podstawie kodu. Jednak, żeby dokumentacja była bardziej przydatna należy w naszym kodzie dodawać komentarze opisujące poszczególne jego fragmenty. Przykładem może być komentarz przed funkcją, w którym opiszemy za co ta funkcja odpowiada i jakie przyjmuje parametry.

/** * To jest MojaKlasa. */ export default class MojaKlasa {
/**
* @param {number} a - liczba a.
* @param {number} b - liczba b.
* @return {number} wynik sumowania a i b.
*/
sum(a, b){
    return a + b;
  }
}

Szczerze polecam pisanie komentarzy dokumentujących od razu podczas pisania kodu. To podejście sprawi, że dokumentacja będzie zawsze możliwa do wygenerowania, więc uniknie się tego zajęcia na końcu projektu. Sprawi też, że będzie lepiej napisana bo komentarze będą powstawać na świeżo, kiedy nie musimy przypominać sobie, co do czego służy. Myślę, że to bardzo dobry nawyk, obowiązkowy u każdego „zawodowca” ;)