Dokumentowanie funkcji

Założenie: Nauczymy się, jak pisać czytelną dokumentację dla własnych funkcji w PHP, aby ułatwić ich zrozumienie i późniejsze użycie.

Krok po kroku:

1. Krok 1: Podstawowa dokumentacja. Użyjmy komentarzy docblock, aby opisać funkcję.

   
   /**
    * Dodaje dwie liczby.
    *
    * @param int $a Pierwsza liczba.
    * @param int $b Druga liczba.
    * @return int Suma dwóch liczb.
    */
   function dodaj(int $a, int $b): int {
     return $a + $b;
   }
   				

   Ten kod definiuje funkcję `dodaj`, która dodaje dwie liczby całkowite i zwraca ich sumę. Komentarz docblock opisuje parametry i wartość zwracaną.

2. Krok 2: Dokumentacja bardziej zaawansowana. Dodajmy opis wyjątków.

   
   /**
    * Dzieli dwie liczby.
    *
    * @param float $a Liczba dzielna.
    * @param float $b Liczba dzielnik.
    * @return float Wynik dzielenia.
    * @throws DivisionByZeroError Jeżeli $b jest równe 0.
    */
   function dziel(float $a, float $b): float {
     if ($b == 0) {
       throw new DivisionByZeroError("Nie można dzielić przez zero!");
     }
     return $a / $b;
   }
   				

   Tutaj dodaliśmy informację o wyjątkach, które mogą być rzucone przez funkcję.

3. Krok 3: Użycie @return. Precyzyjne określenie typu zwracanej wartości.

   
   /**
    * Zwraca tablicę z liczbami od 1 do n.
    *
    * @param int $n Liczba określająca górną granicę zakresu.
    * @return array Tablica liczb.
    */
   function liczbyDoN(int $n): array {
     $result = [];
     for ($i = 1; $i <= $n; $i++) {
       $result[] = $i;
     }
     return $result;
   }
   				

   W tym przykładzie dokładnie określamy typ zwracanej wartości jako tablicę.

Ten wpis przedstawia podstawy dokumentowania funkcji w PHP. Zachęcamy do dalszego zgłębiania tematu i eksperymentowania z różnymi rodzajami komentarzy docblock!