Ja np.: pisząc dokumentację kieruję się opisami funkcji.
Jeśli klient wyamga aby dokumentacja była w osobnym pliku tekstowy zbieram wszystkie komentarze funkcji jakie piszę w czasie tworzenia kodu i w pliku je trochę rozszerzam o szczegóły, które w komentarzach do kodu były zbędne.
Jesli chodzi o schemat komentarzy to u mnie wygląda tak:
/**
* Zbieranie danych o kategoriach
*
* @param array $params tablica filtrów wyszukiwania
*
* @return bool/array FALSE jeśli brak kategorii, jesli kategoria istnieje - tablica z danymi
*/
Wydaje mi się, że to standardowy komentarz do funkcji