niedziela, 11 grudnia 2011

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:
Promuj

2 komentarze:

  1. Fajny blok dodaję do ulubionych.
    +
    Mała uwaga Sandcastle tez generuje formułę służącą do opisania funkcji, wystarczy nad funkcja wpisać /// z klawiatury i cała struktura jest włącznie z parametrami i return zostaje utworzona wystarczy uzupełnić.

    OdpowiedzUsuń
  2. Dzięki za zainteresowanie blogiem.

    Przepraszam za zwłokę w odpowiedzi, ale w ramach uzupełnienia: to nie Sandcastle generuje formułę do opisu funkcji a sam Visual Studio. Zgadza się GhostDoc nie jest wymagany, ale gdybyś go wypróbował, to okazałoby się, że na prawdę jest pomocny i generuje automatycznie znacznie więcej opisu niż robi to Visual Studio. Niemniej jednak nie trzeba używać, a wielu wystarczy sam VS.

    OdpowiedzUsuń

Posty powiązane / Related posts