Zadanie 2: Dokumentacja Projektowa i Własny Projekt

Wstęp

W poprzednim zadaniu nauczyłeś się podstaw składni JSDoc. Teraz czas na zastosowanie tej wiedzy w praktyce w nieco większej skali. W pracy programisty często spotkasz się z koniecznością dopisania dokumentacji do istniejącego kodu ("legacy code") lub tworzenia nowego projektu, który musi być czytelny dla zespołu od pierwszego dnia.

Cel zadania

Uzupełnienie dokumentacji JSDoc dla dostarczonych plików symulujących system e-commerce.
Zaprojektowanie, napisanie i pełne udokumentowanie własnego, małego projektu JavaScript.

Część 1: Dokumentacja Systemu E-commerce

Poniżej znajdują się dwa pliki: produkt.js (klasa reprezentująca produkt) oraz koszyk.js (logika koszyka zakupowego). Twoim zadaniem jest stworzenie tych plików i dodanie do nich szczegółowych komentarzy JSDoc.

Wymagania dla Części 1:

Utwórz folder sklep_internetowy.
Skopiuj poniższy kod do odpowiednich plików.
Opisz wszystkie klasy, konstruktory, metody i parametry używając tagów: @class, @constructor, @param, @returns, @description (domyślny), @example (dodaj przykłady użycia!).

Plik: `produkt.js`

class Produkt {
    constructor(nazwa, cena, kategoria) {
        this.id = Math.floor(Math.random() * 1000);
        this.nazwa = nazwa;
        this.cena = cena;
        this.kategoria = kategoria;
    }

    pobierzInfo() {
        return `${this.nazwa} (${this.kategoria}) - ${this.cena} PLN`;
    }

    zmienCene(nowaCena) {
        if (nowaCena > 0) {
            this.cena = nowaCena;
            return true;
        }
        return false;
    }
}

Plik: `koszyk.js`

class Koszyk {
    constructor() {
        this.produkty = [];
    }

    dodajProdukt(produkt, ilosc = 1) {
        this.produkty.push({ produkt, ilosc });
    }

    obliczSume() {
        let suma = 0;
        for (let item of this.produkty) {
            suma += item.produkt.cena * item.ilosc;
        }
        return suma;
    }

    wyswietlKoszyk() {
        return this.produkty.map(item => 
            `${item.produkt.nazwa} x${item.ilosc}`
        ).join('\n');
    }
}

Wskazówka: Pamiętaj o wygenerowaniu dokumentacji poleceniem npx jsdoc produkt.js koszyk.js i sprawdzeniu efektu w out/index.html.

Część 2: Własny Projekt

To jest najważniejsza część zadania. Musisz wcielić się w rolę architekta i programisty.

Wymagania:

Wymyśl temat projektu (np. "System zarządzania biblioteką", "Gra RPG w konsoli", "Kalkulator finansowy", "Organizer zadań"). Wybierz coś, co Cię interesuje!
Projekt musi składać się z minimum 3 plików .js (moduły lub po prostu oddzielne pliki logiczne).
Użyj Klas (Classes) lub Funkcji konstruktora.
Kod musi być w pełni udokumentowany za pomocą JSDoc (każda funkcja, każda zmienna kluczowa).
Wygeneruj stronę z dokumentacją.

Co oceniamy?

Jakość dokumentacji: Czy opisy są jasne? Czy użyto odpowiednich typów zmiennych?
Struktura kodu: Czy podzieliłeś kod sensownie na pliki?
Kreatywność: Ciekawy pomysł na projekt będzie dodatkowym atutem.

Zadanie do oddania

Zrzut ekranu wygenerowanej dokumentacji z Części 1.
Spakowany folder z Częścią 2 (Twój własny projekt), zawierający kod źródłowy oraz wygenerowany folder out z dokumentacją HTML.

Dokumentacja Projektowa i Własny Projekt