pisanie dokumentacji z GhostDoc

Promuj

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? ;)

2 Responses to pisanie dokumentacji z GhostDoc

  1. wozni pisze:

    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

  2. netmajor pisze:

    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 ;)

Skomentuj

Wprowadź swoje dane lub kliknij jedną z tych ikon, aby się zalogować:

Logo WordPress.com

Komentujesz korzystając z konta WordPress.com. Log Out / Zmień )

Zdjęcie z Twittera

Komentujesz korzystając z konta Twitter. Log Out / Zmień )

Facebook photo

Komentujesz korzystając z konta Facebook. Log Out / Zmień )

Google+ photo

Komentujesz korzystając z konta Google+. Log Out / Zmień )

Connecting to %s