Zadania na lekcje

Wprowadzenie do JSDoc

Javascript
Priorytet: Normalny Szkic

Zadanie 1: Wprowadzenie i instalacja JSDoc

Wstęp

Dobra dokumentacja to podstawa każdego profesjonalnego projektu. JSDoc to standard komentowania kodu w JavaScript, który pozwala nie tylko opisywać działanie funkcji dla innych programistów, ale także automatycznie generować czytelne strony z dokumentacją API (HTML). Działa to podobnie do JavaDoc w Javie.

Cel zadania

Zainstalowanie biblioteki JSDoc, konfiguracja środowiska Node.js (inicjalizacja projektu) oraz udokumentowanie pierwszych prostych funkcji.

Wymagania techniczne

  1. Zainstalowane środowisko Node.js.
  2. Podstawowa umiejętność obsługi terminala/konsoli.

Kroki do wykonania

1. Przygotowanie projektu

Najpierw musimy stworzyć miejsce na nasz projekt i zainicjować go jako pakiet npm.

  1. Stwórz nowy folder o nazwie jsdoc_cwiczenia.
  2. Otwórz ten folder w swoim edytorze kodu (np. VS Code).
  3. Otwórz terminal w tym folderze i wpisz polecenie, aby utworzyć plik package.json: 
    npm init -y

2. Instalacja JSDoc

Zainstaluj JSDoc jako tzw. devDependency (zależność potrzebną tylko podczas tworzenia aplikacji, a nie jej działania):

npm install --save-dev jsdoc

3. Pierwszy udokumentowany kod

Stwórz plik matematyka.js i wklej do niego poniższy kod. Zwróć uwagę na specjalne komentarze zaczynające się od /**:

/**
 * Dodaje dwie liczby do siebie.
 * @param {number} a - Pierwsza liczba (składnik).
 * @param {number} b - Druga liczba (składnik).
 * @returns {number} Wynik dodawania (suma).
 */
function dodaj(a, b) {
    return a + b;
}

/**
 * Odejmuje drugą liczbę od pierwszej.
 * @param {number} a - Odjemna.
 * @param {number} b - Odjemnik.
 * @returns {number} Wynik odejmowania (różnica).
 */
function odejmij(a, b) {
    return a - b;
}

/**
 * Mnoży dwie liczby.
 * @param {number} x - Czynnik pierwszy.
 * @param {number} y - Czynnik drugi.
 * @returns {number} Iloczyn.
 */
const pomnoz = (x, y) => x * y;

4. Generowanie dokumentacji HTML

Teraz najważniejszy moment - wygenerowanie strony z dokumentacją na podstawie Twoich komentarzy. W terminalu wpisz:

npx jsdoc matematyka.js

Powinien pojawić się nowy folder o nazwie out.

  1. Wejdź do folderu out.
  2. Otwórz plik index.html w swojej przeglądarce internetowej.
  3. Powinieneś zobaczyć automatycznie wygenerowaną stronę z opisem Twoich funkcji dodaj, odejmij i pomnoz.

[!IMPORTANT] Zadanie do oddania: Prześlij zrzut ekranu wygenerowanej strony HTML z dokumentacją (plik out/index.html otwarty w przeglądarce) lub spakowany folder projektu (bez node_modules).