dokumentacja kodu, jak??? Opcje

[mrok]

Mam pytanie jak tworzycie dokumentację do kodu?

Nurtuje mnie takie pytanie ponieważ mam trochę styczności z branżą budowlaną i tam zawsze jest dużo papieru, projekty i rysunki. Ja natomiast do tej pory w kwestii dokumentacji miałem styczność tylko z czymś na kształt:
- opisu wymagać "Klient loguje się, edytuje profil, dodaje wpis'
- dokumentacji opisowej jak powyżej, ale z szczegółowo rozrysowanymi makietami, formularzami, etc
- UML (słabo go jeszcze znam) - gdzie był jeden aktor i pełno odnośników do akcji które może wykonać.

Wszystkie powyższe są fajne i na pewno dużo lepsze niż "zrób mi ekstra stronkę jak nk i allegro na jutro', ale wyobraźcie sobie, że trzeba np do każdej akcji dodać powiadamianie użytkownika na maila. Powyższe dokumenty to sporo czytania i nic nie mówią o kodzie... nawet jak je przeczytam 20 razy to nie wiem czy muszę grzebać w kontrolerze xxx w linii zzz czy gdzieś indziej. Idealna sytuacja to patrzę i tuż przed wysłaniem odpowiedzi do przeglądarki jest jakiś dispatcherShutdown ktory kończy każdą akcje.

Ot analogia do budowy - kierownik patrzy w plany i mówi, że trzeba w tej konkretnej ścianie kuć 0.4m na podłogą i znaleźć jakąś rurkę, ja natomiast musiałbym przekuć całą ścianę (kod) żeby znaleźć tę rurkę.

I tu pytanie czy takie projekty w przypadku programistów są możliwe do zrealizowania? Czy istnieją a ja jeszcze o nich nie wiem )
Jak Wy rozwiązujecie ten problem?

Wybaczcie jeśli taki temat już się pojawił - ale nie wiem nawet czego szukam żeby to sprawdzić

[wookieb]

Składnia phpdoc jest dość dobrym sposobem na udokumentowanie kodu. Dodatkowo są narzedzia, która na podstawie owej składni tworzą ci gotowy dokument html.
Php documentator, dodatkowo wspiera możliwość pisania nie tylko dokumentacji kodu, ale także opisywania całych modułów.

[mrok]

Składnia phpdoc jest dość dobrym sposobem na udokumentowanie kodu. Dodatkowo są narzedzia, która na podstawie owej składni tworzą ci gotowy dokument html.
Php documentator, dodatkowo wspiera możliwość pisania nie tylko dokumentacji kodu, ale także opisywania całych modułów.

Taak zapomniałem wspomnieć o documentatorze, ale widzisz wookieb to nadal jest opis tekstowy - szukam jakiegoś rozwiązania z rysunkami
- przypadkiem znalazłem coś takiego diagram i muszę trochę się w to zagłębić bo może to jest rozwiązanie którego poszukuję.


P.S. Często tak mam że szukam czegoś cały dzień, a dopiero jak napiszę o tym na forum to rozwiązanie samo się znajduje - całkiem przypadkiem

[wookieb]

No tak, ale to diagramy tworzy się oddzielnie. W phpdocu jest narzędzie do pisania manual booków i tam możesz spokojnie wstawiać obrazki.

[darko]

Obrazek, do którego podałeś link wygląda na schemat przypadków użycia wykonany w Umbrello.

[mrok]

Obrazek, do którego podałeś link wygląda na schemat przypadków użycia wykonany w Umbrello.

Dzieki za nazwę programu.