Zadanie 3: Klasy i Interfejsy w JSDoc

Wstęp

JavaScript (przed ES6) nie posiadał klas, a nawet teraz "klasy" to lukier składniowy na prototypach. JSDoc pozwala nam jednak precyzyjnie opisać strukturę obiektową, w tym interfejsy, które w czystym JS nie istnieją. Dzięki temu IDE (jak VS Code) może podpowiadać błędy, gdy klasa nie implementuje wymaganych metod.

Cel zadania

Nauczyć się dokumentować klasy, konstruktory oraz symulować interfejsy za pomocą tagów @interface i @implements.

Nowe tagi JSDoc

@class - Oznacza funkcję lub klasę ES6 jako konstruktor klasy.
@constructor - (Opcjonalne w ES6) Wskazuje funkcję konstruktora.
@interface - Definiuje interfejs (zbiór metod, które klasa musi posiadać).
@implements {NazwaInterfejsu} - Wskazuje, że klasa implementuje dany interfejs.

Kroki do wykonania

1. Przygotowanie

Stwórz folder jsdoc_klasy.
Zainicjuj projekt (npm init -y) i zainstaluj JSDoc (npm install --save-dev jsdoc), jeśli nie masz tego globalnie lub z poprzedniego zadania.

2. Kod do uzupełnienia

Stwórz plik users.js. Poniżej znajduje się kod, który musisz uzupełnić o brakującą dokumentację JSDoc.

Twoim zadaniem jest:

Zdefiniować interfejs AuthMethod z metodą authenticate.
Opisać klasę User i jej metody.
Opisać klasę Admin dziedziczącą po User.
Opisać klasę GoogleAuth, która implementuje AuthMethod.

Kod do wklejenia (bez komentarzy JSDoc - Twoim zadaniem jest je dodać):

/* TU ZDEFINIUJ INTERFEJS AuthMethod (metoda authenticate przyjmuje login i hasło, zwraca boolean) */

class User {
    constructor(name, email) {
        this.name = name;
        this.email = email;
        this.isActive = true;
    }

    login() {
        console.log(`${this.name} zalogowany.`);
    }

    getDetails() {
        return `Użytkownik: ${this.name} (${this.email})`;
    }
}

class Admin extends User {
    constructor(name, email, permissions) {
        super(name, email);
        this.permissions = permissions;
    }

    deleteUser(user) {
        console.log(`Admin ${this.name} usuwa użytkownika ${user.name}`);
    }
}

/* TU DODAJ @implements */
class GoogleAuth {
    authenticate(login, password) {
        // Symulacja logowania
        return true;
    }
}

3. Wzór dokumentacji (Podpowiedź)

Oto jak powinny wyglądać fragmenty dokumentacji, które musisz stworzyć:

Definicja interfejsu:

/**
 * Interfejs do obsługi autentykacji.
 * @interface AuthMethod
 */

/**
 * Metoda autoryzująca użytkownika.
 * @function
 * @name AuthMethod#authenticate
 * @param {string} login
 * @param {string} password
 * @returns {boolean}
 */

Implementacja interfejsu:

/**
 * Autentykacja przez Google.
 * @implements {AuthMethod}
 */
class GoogleAuth { ... }

4. Generowanie i Weryfikacja

Wygeneruj dokumentację: npx jsdoc users.js.
Otwórz out/index.html.
Sprawdź zakładkę "Classes" oraz "Interfaces" (powinna się pojawić, jeśli poprawnie użyłeś @interface).

Zadanie do oddania

Prześlij plik users.js z pełnymi komentarzami JSDoc.

Dokumentowanie Klas i Interfejsów w JSDoc