Zadanie 1: Instalacja i podstawy JSDoc

Wstęp

Pisanie kodu to tylko połowa sukcesu. Drugą połową jest sprawienie, aby inni (i Ty sam za pół roku) zrozumieli, co ten kod robi. W świecie JavaScript standardem dokumentowania jest JSDoc. To nie tylko komentarze – to potężne narzędzie, które generuje strony www z dokumentacją Twojego projektu.

Cel zadania

Zainstalowanie JSDoc w projekcie, skonfigurowanie go oraz wygenerowanie pierwszej strony z dokumentacją dla przykładowej funkcji.

Wymagania techniczne

Instalacja: Utworzenie projektu NPM i instalacja pakietu jsdoc.
Konfiguracja: Dodanie skryptu uruchamiającego w package.json.
Dokumentacja: Opisanie jednej funkcji przy użyciu standardu JSDoc.
Generowanie: Zbudowanie statycznej strony HTML z dokumentacją.

Kroki do wykonania

1. Inicjalizacja projektu

Aby zainstalować narzędzia, musisz mieć projekt Node.js. Utwórz nowy folder i uruchom w nim terminal.

# Inicjalizacja pustego projektu (utworzy pakiet.json)
npm init -y

Następnie zainstaluj JSDoc jako "zależność deweloperską" (nie jest potrzebna do działania aplikacji, tylko do jej tworzenia).

npm install --save-dev jsdoc

2. Przygotowanie kodu

Stwórz plik math.js i wklej do niego prostą funkcję. Dodaj nad nią specjalny komentarz rozpoczynający się od /**.

/**
 * Dodaje dwie liczby.
 * 
 * @param {number} a - Pierwsza liczba do dodania.
 * @param {number} b - Druga liczba do dodania.
 * @returns {number} Suma dwóch liczb.
 */
function add(a, b) {
    return a + b;
}

3. Konfiguracja uruchamiania

Najwygodniej uruchamiać JSDoc przez NPM. Otwórz plik package.json i w sekcji "scripts" dodaj polecenie doc.

/* package.json */
{
  "scripts": {
    "doc": "jsdoc -c jsdoc.json"
  }
}

[!NOTE] Na razie użyjemy prostszego polecenia bez pliku konfiguracyjnego jsdoc.json. Zmień powyższy skrypt na: "doc": "jsdoc math.js" To wystarczy na początek.

4. Generowanie dokumentacji

Uruchom w terminalu polecenie:

npm run doc

W Twoim folderze pojawi się nowy katalog out. Otwórz w przeglądarce plik out/index.html.

[!IMPORTANT] Commit: Pierwsza wygenerowana dokumentacja.

5. Zadanie dla chętnych: TypeDoc (TypeScript)

Jeśli używasz TypeScript, JSDoc też działa, ale lepszym narzędziem jest TypeDoc.

Zainstaluj: npm install --save-dev typedoc
Uruchom: npx typedoc math.ts Obsługuje ono typy automatycznie, bez konieczności dublowania ich w komentarzach @param {number}.

Narzędzia: Dokumentacja kodu z JSDoc