Tworzę projekt w django, konkretnie to skrypt forum i zastanawiam się jak się tworzy dokumentacje? Nigdy nie robiłem niczego większego i nie pracuje jeszcze wiec nie mam doświadczenia.
0
0
O jaką dokumentacje chodzi dokładnie? Doxygen i pydoc?
0
Jeżeli pytasz co powinna taka dokumentacja zawierać to na pewno listę obiektów (klasy interfejsy etc) ich metody wraz z parametrami jakie przyjmują/zwracają, co robią oraz ewentualne błędy jakie mogą wyrzucić i parę przykładów jak to wykorzystać by się przydało.
0
Gdzie to tworzyć? Jako dodatkowy plik czy zbiór plików umieszczony gdzieś przy kodach źródłowych?
usunięcie cytowania całego poprzedniego posta - fp
0
Kolega wyżej napisał, najłatwiej skorzystać z gotowych narzędzi do tego, Doxygen moim zdaniem najlepiej się prezentuje (no i masz ją online), możesz to pisać w zwykłych plikach tekstowych,MS Word czy w formie html'owej stronki jak chcesz i będzie ci łatwiej. Jeżeli o mnie chodzi to raczej robiłem to w HTML, tworzyłem sobie katalog doc, w nim index główny, który prowadził do podstron, które opisywały klasy i metody oraz info z jakich zasobów/bibliotek zew. korzysta mój kod. Jeżeli masz zamiar stworzyć własny wizerunek dokumentacji to możesz się popatrzeć na wyglądają inne dokumentacje np http://msdn.microsoft.com/en-us/library/windows/desktop/ms706795%28v=vs.85%29.aspx (Windows WIFI API), http://www.yiiframework.com/doc/api/ (Yii Framework PHP)
0
Generalnie robię swoją aplikacje i łapie się na tym, że zapominam po kilku dniach co robi dana funkcja i musze szukać w kodzie
0
Visual C++ Professional + Visual assist - podczas podpowiadania składni może wyświetlać komentarz znajdujący się przy funkcji ;)
0
Wiele języków ma jakieś domyślne narzędzia do generowania dokumentacji, jednak czasem lepiej użyć zewnętrznych (porównanie masz na Wiki). Przykładowo:
- Ruby - RDoc (domyślne), YARDoc (chyba najpopularniejsze) oraz SDoc
- Java - JavaDoc, Doxygen, etc.
- D - Ddoc
- etc.
Musisz tylko przeczytać jak umieszczać dokumentację w kodzie (np. Python używa DocStringów).
0
1
qaweasdzcx napisał(a):
Generalnie robię swoją aplikacje i łapie się na tym, że zapominam po kilku dniach co robi dana funkcja i musze szukać w kodzie
To nie jest problem z dokumentacją lecz z nazwą funkcji. Nazywaj je dobrze, to nie będziesz musiał się zastanawiać, co robią. No i oczywiście trzeba pamiętać o tym, że jedna funkcja ma robić tylko jedną rzecz.
0
somekind napisał(a):
qaweasdzcx napisał(a):
Generalnie robię swoją aplikacje i łapie się na tym, że zapominam po kilku dniach co robi dana funkcja i musze szukać w kodzie
To nie jest problem z dokumentacją lecz z nazwą funkcji. Nazywaj je dobrze, to nie będziesz musiał się zastanawiać, co robią. No i oczywiście trzeba pamiętać o tym, że jedna funkcja ma robić tylko jedną rzecz.
W sumie źle się troche wyraźiłem bo nazwy funkcji są dobre tylko wystarczy poprawic kod po za funkcjami i będzie dobrze. Dzięki za wypowiedzi.