Javadoc do dokumentacji projektu

Question

Chcę udokumentować projekt Java, nad którym pracuję. W przeszłości zazwyczaj dokumentowałem interfejs API do projektowania i oprogramowania na wiki. Jednak po niedawno użyciu Mockito do testów szyderczych, byłem pod wrażeniem ilości i jakości dokumentacji na poziomie projektu w rzeczywistych javadocs.

Moje pytanie brzmi, czy ludzie zazwyczaj używają Javadocs do dokumentowania widoku wyższego poziomu projektu (np. Architektury, decyzji dotyczących projektowania itp.), Czy też tego rodzaju informacji najlepiej udokumentowano na (powiedzmy) wiki?

Answer 1

To zależy od tego, kim są Twoi odbiorcy.

Jeśli twoi odbiorcy będą korzystać głównie z interfejsu API, ogólnie lepiej jest inwestować w jasne, zwięzłe opisy (z przykładami) w Javadoc. Jeśli widzowie prawdopodobnie nigdy nie zobaczą interfejsu API, lepiej będzie zachować dokumentację poza Javadoc. Jest to przede wszystkim funkcja nawigowania dokumentacji; Nawigacja Javadoc ułatwia proces programowania.

Jeśli chcesz umieścić dokumentację na wiki lub w pliku PDF, to zależy to od odbiorców. Jeśli jedynym powodem dla wiki jest posiadanie dokumentu HTML w formie odwzorowania strony internetowej, użycie czegoś podobnego do Docbook może zapewnić taką dokumentację z dodatkową korzyścią możliwości generowania reprezentacji PDF tej samej dokumentacji. Jeśli naprawdę masz aktywną społeczność, wiki świeci w zdolnościach pozwalających niemal nieznajomym modyfikować twoją dokumentację.

Określ, czy mocne strony produktów są zgodne z Twoimi potrzebami, a jeśli tak, to jest to właściwy wybór.

Answer 2

Javadoc doskonale nadaje się do generowania dokumentacji na poziomie API. Używam wiki do mojej dokumentacji wysokiego poziomu. Używam confluence jako mojej wiki i istnieje kilka wtyczek, których możesz użyć do tworzenia diagramów architektonicznych.