Przejdź do głównej zawartości
Codex13

69. Dokumentacja kodu PHP — PHPDoc, @param, @return i generowanie dokumentacji

O czym jest to opracowanie?

Dział zatytułowany „O czym jest to opracowanie?”

Dokumentacja kodu PHP

PHPDoc to standard dokumentowania kodu PHP przez komentarze blokowe (DocBlocks). Adnotacje @param, @return, @throws, @var opisują typy i zachowanie kodu. IDE (PhpStorm, VS Code) używa PHPDoc do podpowiedzi. PhpDocumentor generuje z kodu stronę HTML dokumentacji.

Dlaczego warto to znać?

Dział zatytułowany „Dlaczego warto to znać?”
  • IDE używa PHPDoc do autocomplete i sprawdzania typów
  • Starszy kod PHP bez deklaracji typów (PHP 5.x) dokumentowany przez PHPDoc
  • phpDocumentor generuje dokumentację API biblioteki automatycznie

Cel Twojego opracowania

Dział zatytułowany „Cel Twojego opracowania”
  1. Wyjaśnić czym jest DocBlock i kiedy go pisać
  2. Opisać najważniejsze adnotacje: @param, @return, @throws, @var
  3. Omówić typy złożone: union, nullable, array typów
  4. Pokazać generowanie dokumentacji przez phpDocumentor

Zakres obowiązkowy

Dział zatytułowany „Zakres obowiązkowy”
  1. DocBlock — blok komentarza przed klasą lub metodą
  2. @param — opis parametru z typem
  3. @return — opis wartości zwracanej
  4. @throws — dokumentowanie wyjątków
  5. @var — opis właściwości klasy
  6. Typy złożone: string|null, array<int, User>, list<string>
  7. phpDocumentor — instalacja i generowanie HTML

Wymagane przykłady kodu

Dział zatytułowany „Wymagane przykłady kodu”

Przykład 1

Klasa z pełnymi DocBlockami dla wszystkich metod

Przykład 2

Typy złożone: nullable, union, generic array

Przykład 3

Porównanie: kod z typami PHP 8 vs kod tylko z DocBlock

Proponowana struktura pracy

Dział zatytułowany „Proponowana struktura pracy”
  1. Wstęp — dokumentacja w kodzie
  2. DocBlock — format i kiedy pisać
  3. Adnotacje @param, @return, @throws
  4. Typy złożone
  5. Inne adnotacje: @var, @since, @deprecated
  6. Generowanie dokumentacji
  7. Kiedy PHP type hints zastępują DocBlock
  8. Podsumowanie i bibliografia

Pytania kontrolne

Dział zatytułowany „Pytania kontrolne”

Najczęstsze błędy

Dział zatytułowany „Najczęstsze błędy”

Zasoby

Dział zatytułowany „Zasoby”
phpDocumentor Generator dokumentacji PHP
PSR-5: PHPDoc Standard Propozycja standardu PHPDoc
PHPStan: Generics Typy generyczne przez PHPDoc

Do dzieła!

Dział zatytułowany „Do dzieła!”

Dodaj DocBlocks do swojego projektu!

Weź klasę lub funkcje z miniprojektu i dodaj pełne DocBlocks. Zainstaluj phpDocumentor i wygeneruj stronę HTML. Zrób screenshot do opracowania.