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 (IMG:style_emoticons/default/winksmiley.jpg) )
Jak Wy rozwiązujecie ten problem?

Wybaczcie jeśli taki temat już się pojawił - ale nie wiem nawet czego szukam żeby to sprawdzić (IMG:style_emoticons/default/questionmark.gif) (IMG:style_emoticons/default/questionmark.gif)