Programiści mają do dyspozycji bogaty wybór narzędzi ułatwiających tworzenie dokumentacji technicznej aplikacji.

Niestety, na tworzenie dokumentacji zespoły programistyczne zazwyczaj poświęcają za mało uwagi. Co prawda w trakcie pisania programu każdy z programistów stara się umieszczać w kodzie odpowiednie komentarze, jednak praktyka pokazuje, że zwykle są one bardzo fragmentaryczne i nie opisują dokładnie specyfikacji czy przeznaczenia funkcji. Spośród dostępnych na rynku narzędzi do tworzenia

dokumentacji można wyodrębnić dwie główne grupy.

Pierwsza grupa

Narzędzia te na podstawie struktury programu tworzą dokumenty, w których umieszczone są nazwy procedur, funkcji, drzewo wywołań czy zależności pomiędzy klasami. Następnie można uzupełniać dokumenty, tworząc opisy poszczególnych funkcji, rolę klas i modułów.

Takie rozwiązanie ma istotne zalety. Po pierwsze - teoretycznie - program nie musi w ogóle zawierać komentarzy. Cała struktura, wszystkie elementy projektu zostaną automatycz- nie zgrupowane, przetworzone i umieszczone w "szablonie" dokumentacji. Przykładem takiej aplikacji są PowerDoc i Delphi Documentor.

PowerDoc na podstawie analizy projektu w Visual Basicu tworzy dokumenty w edytorze Word, zawierające spis klas, obiektów, ich właściwości, metod itp. Ponadto wyodrębnione są grupy właściwości odpowiedzialne np. za wygląd formatki. Jednocześnie opracowywany jest szczegółowy indeks i spis treści - programiści muszą tylko dodać właściwe opisy.

Podobnym rozwiązaniem jest Delphi Documentor. W tym przypadku analizowany jest projekt w Delphi, a dokumen-tacja jest tworzona w HTML. Delphi Documentor potrafi także tworzyć rysunek prezentujący hierarchię klas. Pakiet dyspo- nuje rozbudowanym mechanizmem, pozwalającym filtro- wać dokumentowane elementy projektu, np. można wyłączać niektóre klasy czy określać, że niektóre z zależności nie mają być uwzględniane w dokumentacji.

Narzędziem innej klasy jest CC-RIDER, który jest systemem do przeglądania kodu w C/C++. Pakiet składa się z dwóch części: CC-RIDER Analyzer przetwarza kod źródłowy projektu i tworzy specjalną bazę, pozwalającą przeglądać strukturę projek- tu przy użyciu programu CC-RIDER Visualizer. Na podstawie zawartości tej bazy opracowywana jest dokumentacja w formacie RTF, HTML, HLP lub w zwykłym - tekstowym. Warto dodać, że Analyzer zawiera opcję pozwalającą zsynchronizować bazę CC-RIDER i zmodyfikowany kod źródłowy programu.

Część wizualizacyjna pakietu pozwala przeglądać drzewo zależności pomiędzy funkcjami. W dowolnym momencie można przenieść się do odpowiedniego fragmentu kodu źródłowego. Interfejs CC-RIDER jest bardzo intuicyjny. Pakiet doskonale nadaje się do szybkiego zapoznania ze złożonym projektem nowego programisty w zespole.

CC-RIDER ma jednak wadę. Co prawda opisy niektórych elementów programu są brane z komentarzy w kodzie źródłowym, jednak pakiet zawsze zakłada, że opis w kodzie źródłowym znajduje się nad opisywanym elementem, np. przed deklaracją zmiennej. Wielu programistów uzna ten mechanizm za nieintuicyjny.

Druga grupa

Inna klasa algorytmów tworzenia dokumentacji opiera się na specjalnych znacznikach umieszczanych w obrębie komentarzy. Komentarze pełnią dwie role. Po pierwsze, przypominają o czymś autorowi, np. co oznacza zmienna, lub informują o konieczności poprawki kodu. Tego typu komentarze są nieistotne z punktu widzenia innych programistów, których interesuje tylko znaczenie parametrów formalnych danej procedury. Konieczne jest więc, aby narzędzie do tworzenia dokumentacji rozpoznawało istotne komentarze i pomijało niepotrzebne.

OpenSource ScanDoc jest programem napisanym w Perlu, który analizuje program w C++ pod kątem występowania spec-jalnych znaczników w komentarzu i deklaracji podstawowych typów danych. Szybko tworzy efektownie wyglądającą dokumentację. Można bardzo dokładnie określić wygląd tworzonego dokumentu HTML.

Podobnym rozwiązaniem jest OpenSource DOC++. Pakiet ten pozwala tworzyć dokumentację projektów w języku C++, Java lub interfejsów IDL. Określony jest zbiór zasad formatowania komentarzy. Wielu programistów uważa propozycję DOC++ za najwygodniejszy sposób pisania komentarzy.

Dokument HTML tworzony przez DOC++ jest tak naprawdę witryną WWW, na której można poruszać się po poszczególnych elementach dokumentacji czy przejść bezpośrednio do kodu źródłowego. DOC++ analizuje także powiązania pomiędzy elementami kodu, związki między plikami czy tworzy rysunki obrazujące strukturę obiektową zaimplementowaną w programie.

DOC++ może tworzyć dokumentację w postaci HTML, a także jako pliki TeX, co pozwala na uzyskanie efektownej dokumentacji drukowanej.

Komercyjnym pakietem tworzenia dokumentacji projektu Visual Basic jest Document! VB. Automatycznie przegląda on projekt i buduje plik, odpowiadający jego strukturze, a jednocześnie może odczytać z komentarzy właściwy opis danych elementów. Tworzony jest plik w formacie HTML Help bardzo przypominający dokumentację API znajdującą się w MSDN.

Warto wspomnieć o jednej propozycji systemu tworzenia dokumentacji ułatwiającej opis API programu opracowanego w Javie. JavaDoc to specjalny parser, który analizuje deklaracje i sformatowane komentarze w kodzie źródłowym w Javie. Jest to część pakietu JDK. Tym, co wyróżnia pakiet, jest mechanizm tworzenia dokumentacji. Parser wymaga określenia tzw. docleta, który odpowiada za sformatowanie tekstu, sposób generowania hierarchii klas itp. Standardowy doclet tworzy dokumentację w HTML. Można jednak napisać doclet, który tworzy pliki w formacie RTF czy MIF. Jednocześnie doclet może pełnić rolę "diagnostyczną". Jest on wywoływany podczas analizy kodu, może więc sprawdzać, czy są zachowane zasady nazewnictwa zmiennych, czy parametry są opisa-ne w komentarzu itp. Jest to bardzo potężne narzędzie, które jednocześnie pozwala tworzyć dokumentację i analizować kod.

Tworzenie dokumentacji na podstawie specjalnie sformatowanego komentarza i analizy strukturalnej projektu jest chyba najwygodniejszym rozwiązaniem. Dzięki temu programista może skupić się na opraco- waniu aplikacji i jest niejako "zmuszony" do dokumentowania swojej pracy.

Grupa trzecia

Można wyodrębnić trzecią kategorię narzędzi do tworze- nia dokumentacji, związanych z komponentami ActiveX/ COM. W przypadku gdy firma sprzedaje komponenty do wykorzystania przez innych programi- stów, konieczne jestdostarczenie im szczegółowej dokumentacji interfejsów.

Obiekt COM zawiera opisy metod i podstawowych klas. Powstało wiele narzędzi, które na podstawie tych informacji tworzą szkielet dokumentacji w formacie HTML Help. Prostym narzędziem tego typu jest bezpłatny ComAssistant. Bardziej wyrafinowany VBDOCX pozwala np. przygotowywać przykłady wywołań w Delphi, C++ czy Visual Basicu.