[PL] pisanie dokumentacji z GhostDoc
W kodzie C# możemy tworzyć komentarze przy pomocy XML. Na podstawie tych komentarzy można później wygenerować pliki z dokumentacją przy pomocy odpowiednich narzędzi. Zawsze jednak strasznie nie chciało mi się pisać komentarzy do kodu. Zajęcie to jest nudne i czasochłonne (czasem nic po prostu nie przychodzi do głowy). Z GhostDoc (dodatek do Visual Studio) wszystko może ulec zmianie. Narzędzie to służy do generowania komentarzy XML za nas. Jak sam autor zaznacza w prezentacji, GhostDoc nie czyta w myślach (jaka szkoda!). Zdarzyć się może, że narzędzie wygeneruje jakiś kompletnie bezsensowny komentarz. Jednak kilka pierwszych testów wykonanych przeze mnie było pomyślnych. Przykładowy komentarz wygenerowany przez narzędzie do metody Save w klasie HeroComponent wygląda następująco:
/// <summary>
/// Saves the specified hero.
/// </summary>
/// <param name="hero">The hero.</param>
public static void Save(Hero hero)
{
...
}
Mi taki komentarz w zupełności wystarcza. Z pewnością będą używać GhostDoc do dalszego komentowania kodu.
PS. Autor prezentacji ma chyba najbardziej nudny głos jaki kiedykolwiek słyszałem. Udało się komuś nie ziewnąć podczas oglądania? 😉
A mi się taki komentarz nie podoba 🙂 To jest właśnie przekleństwo generowanej automatycznie dokumentacji. Skoro mam metodę “Save”, która akceptuje parametr typu “Hero” to kontrakt jest jasny. Komentarz powinien być bardziej treściwy, jeżeli ma być z niego jakikolwiek pożytek, w przeciwnym wypadku brak komentarza jest lepszym wyjściem.
Na koniec chciałbym dodać, że autor GhostDoc prezentuje takie samo stanowisko o czym przypomina pare razy w prezentacji.
Pozdrawiam
Od jakiegoś czasu używam GhostDoc wraz z Doxygen do generowania htmlowo zorientowanej dokumentacji. Co do samych komentarzy to są one bardzo pomocne, jednak należy zrozumieć, że generuje on przykładowe komentarze na podstawie paramentów w metodzie, więc to od tego jak opiszemy parametry zależy jak dobrze nasze narzędzie je opisze 😉