Tworzenie dokumentacji Opcje

[rad11]

Co wedlug was powinna posiadac dobra dokumentacja aplikacji? Czym sie kierujecie piszac taka dokumentacje? Co jest najwazniejsze? Czy korzystacie z jakis szablonow?

[SpiritCode]

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:

[PHP] pobierz, plaintext 
/**
* 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
*/
[PHP] pobierz, plaintext 

Wydaje mi się, że to standardowy komentarz do funkcji

Ten post edytował SpiritCode 29.01.2015, 08:05:39

[PrinceOfPersia]

no i przepuszcza się takie pliki przez jakiś generator dokumentacji, który automatycznie ci wygeneruje pliki w formacie HTML czy innym na podstawie komentarzy w kodzie (jaki konkretnie generator? To już zależy od języka programowania, ale ogólna zasada chyba jest taka, że bierzesz nazwę języka programowania i dodajesz słowo doc - np. JSDoc, JavaDoc itp. przypuszczam, że i jakies PHPDoc może istnieć).

Ten post edytował PrinceOfPersia 29.01.2015, 17:37:41

[com]

PrinceOfPersia nie pomyliłeś się istnieje http://www.phpdoc.org/ ale zasada jest w zasadzie wszędzie taka sama, wystarczy się raz tego nauczyć a potem już to robi się automatycznie (IMG:style_emoticons/default/wink.gif)

[mstraczkowski]

Istnieje jeszcze dosyć dobra alternatywa dla PHPDoc
http://www.apigen.org/

Ten post edytował mstraczkowski 3.02.2015, 16:02:31

[rad11]

Właśnie zapoznałem się z "apigen" i calkiem przyjazne jest.