Tworzenie dokumentacji do kodu w C# [PL]

Nie dawno otrzymałem email z pytaniem dotyczącym tworzenia dokumentacji do kodu napisanego w C#:

Poszukuje czegoś do zautomatyzowania procesu tworzenia dokumentacji dla kodu pisanego w C# i trafiłem na (..) temat odnośnie Sandcastle. Czy ten dodatek do Visual Studio pozwala tworzyć dokumentacje dla C# i jest kompatybilny z VS 2010?

Spróbuję w niniejszym wpisie odpowiedzieć na to pytanie.

Na temat tworzenie dokumentacji do oprogramowania pisałem już wcześniej w artykule „Tworzenie dokumentacji”. Wspomniałem tam m.in. o SandCastle, MAML'u (Microsoft Assistance Markup Language) oraz o aplikacji pomocniczej SandCastle Help File Builder (SHBF). Jednak wszystko to dotyczyło tworzenie dokumentacji typu „instrukcja użytkownika”, nie wspominałem tam o możliwości dokumentowania kodu. Warto zauważyć, że sam SandCastle pomaga również w tworzeniu dokumentacji do kodu programu, a wynik jest podobny do takiej dokumentacji, jaką znamy z MSND'a.

Aby można taką dokumentację było wygenerować, należy najpierw zadbać by nasz kod był uzupełniony odpowiednie znaczniki dodawane w komentarzach poprzedzanych trzema slash'ami. Podstawowym znacznikiem będzie „summary” a o innych można przeczytać w wielu artykułach np. na CodeProject, w artykule „C# and XML Source Code Documentation”. Co ciekawe wcale nie musimy sami żmudnie wpisać wspomnianych znaczników, gdyż wystarczy zainstalować dodatek „GhostDoc” (darmowy do użytku niekomercyjnego) i wtedy wystarczy na nazwie klasy lub funkcji, którą chcemy udokumentować kliknąć z menu „Document this” (lub wybrać odpowiedni skrót klawiszowy), by GhostDoc za nas opisał funkcję (na podstawie jej nazwy i parametrów). Np. poniższy komentarz został wygenerowany w sposób automatyczny.

/// <summary>

/// Updates the specified message.

/// </summary>

/// <param name="message">The message.</param>

internal void Update( Message message )

Kolejnym krokiem jest ustawienie kompilatora tak, by generował pliki XML z dokumentacją dla kodu, w przypadku Visual Studio będą to właściwości projektu, zakładka Build i „ptaszek” przy: „XML documentation file”.

Teraz dopiero wkracza SandCastle i SandCastle Help File Builder (SHBF), które nie są dodatkami do Visual Studio, ale odrębnym aplikacjami. SandCastle można by określić mianem silnika generującego dokumentację, podczas gdy SHBF jest przyjaznym interfejsem użytkownika, w który wskazujemy plik DLL lub EXE, dla którego chcemy udokumentować kod, oraz powiązany plik XML wytworzony podczas kompilacji.

Jeżeli chodzi o kompatybilność wspomnianej metody z VS 2010, to nie ma tu żadnego problemu SandCastle, wspiera pliki wytwarzane przez VS 2010 oraz .NET 4.0.

Warto tu również pamiętać, że tak przygotowaną dokumentację można dość łatwo uzupełnić o dowolne artykuły, np. opisujące udokumentowane API, za przykład takiej dokumentacji może posłużyć dokumentacja do OPC UA SDK: http://opcfoundation.org/uasdk/Help/.

Mam nadzieję, że trochę pomogłem, na koniec warto jeszcze przeczytać następujące artykuły:

• http://sakowicz.wordpress.com/2007/05/02/sandcastle-i-generowanie-plikow-pomocy/
• http://polishwords.com.pl/blog/2009/3-sposoby-na-przyspieszanie-wolnego-sandcastle/