Jak tworzyć dokumentacje?

0

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

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).

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.

1 użytkowników online, w tym zalogowanych: 0, gości: 1