Informacje na temat dokumentacji technicznej

Na załączonym do pracy nośniku znajduje się dokumentacja projektowa systemu PROTONET w postaci HTML. Wygenerowano ją za pomocą narzędzia Doxygen opublikowanego w Internecie na zasadach GNU GPL. Autorem tego programu jest Dimitri van Heesch. Do tworzenia diagramów wykorzystuje się program dot z pakietu Graphviz.

Produkt ten umożliwia wygenerowanie dokumentacji w formatach: HTML, RTF, L^ATEX. Pełna dokumentacja w formacie RTF zajmuje około 300 stron wielkości A4, dlatego zdecydowaliśmy się nie dołączać jej do pracy w całości, lecz tylko omówić jej zawartość.

Dokumentacja w postaci HTML zawiera:

• pełną hierarchię klas,
• alfabetyczną listę klas, struktur i unii,
• alfabetyczną listę plików użytych w projekcie,
• alfabetyczną listę wszystkich klas, metod, zmiennych, makrodefinicji, unii i struktur wraz z odnośnikami do dokumentacji klasy, w której je zdefiniowano,
• alfabetyczną listę wszystkich klas, metod, zmiennych, makrodefinicji, unii i struktur wraz z odnośnikami do dokumentacji plików źródłowych, w których zostały zdefiniowane.

Hierarchię klas wygenerowano w postaci tekstowej oraz graficznej. Obie wersje są w pełni hipertekstowe tzn. kliknięcie na nazwę klasy przenosi nas do dokumentacji tej klasy. Na rys. zamieszczono jako przykład fragment graficznej hierarchii klas.

Figure: Fragment graficznej hierarchii klas

Dokumentacja pojedynczej klasy składa się z następujących części.

• Diagram dziedziczenia -- pokazuje miejsce klasy względem klas dziedziczących i dziedziczonych. Na rys. zamieszczono przykładowy diagram dziedziczenia dla klasy L_Interfejs.
• Diagram współistnienia -- pokazuje sposób wykorzystania obiektów dokumentowanej klasy przez obiekty innych klas oraz bazowe dziedziczenie. Na rys. zamieszczono przykładowy diagram współistnienia dla klasy G_Interfejs.
• Dokumentacja wszystkich metod i atrybutów zdefiniowanych w klasie, wraz ze sposobem deklaracji, opisem działania i znaczenia każdego z nich oraz ewentualnym opisem parametrów używanych przez metodę.
• Pełny spis wszystkich metod i atrybutów zdefiniowanych w klasie i odziedziczonych z nadklas.

Figure: Przykładowy diagram dziedziczenia dla klasy L_Interfejs

Figure: Przykładowy diagram współistnienia dla klasy G_Interfejs

Dokumentacja plików źródłowych cpp zawiera diagramy zależności od plików nagłówkowych. Na rys. zamieszczono przykładowy diagram dla pliku data.cpp.

Figure: Przykładowy diagram zależności od plików nagłówkowych dla pliku data.cpp

Dokumentacja plików nagłówkowych składa się z:

• diagramu zależności od innych plików nagłówkowych (na rys. przedstawiono diagram dla pliku l_element.h),
• spisu makrodefinicji,
• spisu definicji typów danych definiowanych w pliku,
• tekstu pliku nagłówkowego z pokolorowaną składnią.

Figure: Przykładowy diagram zależności plików nagłówkowych dla pliku l_element.h