Sugestie dotyczące dokumentacji klasy

Question

Jesteśmy sklepem Microsoft, skoncentrowanym na użyciu języka C#. Mamy kilka projektów, w tym strony internetowe, usługi Windows i biblioteki klas, które zawierają komentarze XML.

Szukam generowania dokumentacji HTML w stylu MSDN dla każdego projektu i rozmieszczenia go w scentralizowanej lokalizacji, do której wszyscy programiści mają łatwy dostęp. Chcę również zautomatyzować te kroki, aby można je było uruchamiać w regularnych odstępach czasu, tak aby ja i inni deweloperzy nie musieli się martwić o to, aby pamiętać o generowaniu i wdrażaniu nowej dokumentacji po każdej zmianie. Spojrzałem na Sandcastle i Doxygen i oba wyglądają na dobre opcje generowania dokumentacji, której potrzebuję, ale potrzebuję porady na temat tego, jak ją zautomatyzować, jak w codziennej pracy czy coś takiego.

Ktoś tam robi coś takiego? Nie jestem sprzedawany, ponieważ końcowy wynik to HTML; zwłaszcza jeśli jest lepszy pomysł.

EDYTOWANIE:

Doceniam wszystkie dobre pomysły. Jest kilka tras, które mogę teraz zbadać, ale nie będę wiedział, które będą najlepsze, dopóki nie zabiorę rąk. Konstruktor plików pomocy Sandcastle wydaje mi się najlepszymi opcjami do tego, co zamierzam zrobić, więc dam wyraz tej sugestii. Jednakże, gdybym miał więcej czasu na pracę nad rozwiązaniami XSLT i CSS, aby uzyskać poprawne dane XML, najpierw skorzystałbym z tej sugestii.

Jeszcze raz dziękuję wszystkim!

Answer 1

Spójrz na Sandcastle Help File Builder. Wykorzystuje to samodzielne projekty, więc możesz je budować tak często, jak chcesz (na przykład co wieczór lub jako część systemu continuous integration za każdym razem, gdy zmiana jest zaznaczona).

Answer 2

Robię to z naszymi projektami. Zasadniczo używamy doxywizard, aby skonfigurować konfigurację Doxyfile, która ustawi specyfikację generowanego html. Następnie w kroku serwera kompilacji wywołuję "doxygen doxyfile".

Nasz Doxyfile jest skonfigurowany do generowania plików doxygen w obszarze widocznym z naszego serwera WWW. Zatem każde zatwierdzenie do trunkingu powoduje automatyczną przebudowę dokumentacji.

Answer 3

Nie potrzebujesz żadnych narzędzi firm trzecich do generowania ładnej dokumentacji: kompilator C# może wyprowadzać dokumentację z komentarzy XML w XML i wszystko czego potrzebujesz to zaprojektowanie ładnego CSS, aby pokazać go w przeglądarce. Jeśli nie jesteś zadowolony, możesz także wygenerować własną transformację XSLT przed zastosowaniem CSS, as described here (poszukaj przykładu CSS w komentarzach!).

Alternatywnie możesz wziąć tę dokumentację XML i ulepszyć ją przy użyciu czegoś takiego jak NDoc. Oto nice article o tym, jak to zrobić, niestety nieco przestarzałe.

Możesz ręcznie zbudować tylko dokumentację swojego projektu w pojedynczy plik XML, uruchamiając kompilator z parametrem /doc:documentationfilename.xml.

Można również wskazać w Visual Studio (Właściwości projektu -> Dokumentacja), aby dodać tę opcję do każdej kompilacji projektu, aby plik XML był generowany przy każdym budowaniu projektu. Następnie można przechwycić zdarzenia po kompilacji, aby skopiować plik XML do repozytorium.

Możesz również skonfigurować swoją kompilację MS na serwerze Team Foundation Server w celu utworzenia dokumentacji i skopiowania jej do repozytorium w podobny sposób (/p:DocumentationFile=fileName.xml);