Poradnik - Doxygen i TeX

DoxygenTeX.md

• Instalacja potrzebnego oprogramowania
  • Doxygen
  • TeX
  • Graphviz
• Doxygen - jak udokumentować program
  • Co należy udokumentować
  • Struktura komentarzy Doxygena
    • Tworzenie komentarza
    • Komendy
• Doxygen - jak wygenerować dokumentację
• Wzór sprawozdania - edycja plików TeX
  • Kod C++ w pliku TeX
• Prawa autorskie

Instalacja potrzebnego oprogramowania

Doxygen

1. Wejdź na stronę Doxygena
2. Pobierz instalator dla systemu Windows (obecny link)
3. Zainstaluj Doxygena

TeX

1. Wejdź na stronę projektu MiKTeX
2. Pobierz instalator dla systemu Windows (obecny link)
3. Zainstaluj TeXa. Aby ułatwić sobie życie, ustaw opcję "Install missing packages on-the-fly: Yes"

Graphviz

1. Wejdź na stronę projektu Graphviz
2. Pobierz instalator dla systemu Windows (obecny link)
3. Zainstaluj Graphviza. Dodaj go do ścieżki, aby Doxygen mógł znaleźć jego pliki wykonywalne

Doxygen - jak udokumentować program

Co należy udokumentować

Samo dokumentowanie nie wymaga instalacji żadnego z powyższych programów. Jedynym wymogiem jest umieszczanie komentarzy w odpowiednim formacie w następujących miejscach (w przypadku C++):

• na początku pliku
• nad przestrzeniami nazw
• nad klasami i strukturami
• nad deklaracjami zmiennych
• nad deklaracjami funkcji

Nie każdy z powyższych fragmentów kodu wymaga udokumentowania. Do zdrowego rozsądku autora programu należy ocenienie, co powinno zostać udokumentowane. Najprostszą zasadą jest udokumentowanie wszystkiego, co znajduje się w plikach nagłówkowych

Struktura komentarzy Doxygena

Komentarze dla Doxygena mogą być różnie skonstruowane, a sam program jest wysoce konfigurowalny, stąd nie ma jedynej słusznej struktury komentarzy. Poniżej opiszę styl komentowania, jaki zastosowałem w projekcie SimpleLogo

Tworzenie komentarza

Styl komentarzy typu Javadoc wymaga rozpoczęcia komentarza sekwencją /** i zakończenia go sekwencją */. Dla klarowności, każda linijka komentarza powinna rozpoczynać się znakiem *. Przykład:

/**
 * Dokumentacja...
 */

W stworzeniu takiego komentarza powinno pomóc IDE użytkownika. W przypadku Visual Studio Code konieczna jest instalacja pluginu Doxygen Documentation Generator

Komendy

Komentarze dla Doxygena należy opatrzyć odpowiednimi komendami. Najczęściej używane komendy:

• @copyright [tekst]
  Notka dotycząca praw autorskich

/**
 * @copyright
 * Copyright 2021 The SimpleLogo Authors.
 * Licensed under GPL-3.0-or-later
 */

• @brief [krótki opis]
  Krótki opis danego fragmentu kodu. Powinien zmieścić się w jednej linijce i być zakończony kropką

/**
 * @brief The code is executed on this Turtle.
 */
Turtle &turtle;

• @param [nazwa parametru] [opis]
  Opis danego parametru funkcji. Powinny zostać opisane wszystkie parametry

/**
 * @brief Handles a procedure call.
 *
 * @param current the call
 * @param argMap current procedure's arguments
 */
 void handleCall(Cmd const &current,
                 std::unordered_map<std::string, double> &argMap);

• @return [typ zwracanej wartości]
  Określa, jaki typ wartości zwraca funkcja. Sama zwracana wartość opisywana jest powyżej

/**
 * @brief Get a reference to tiles.
 *
 * @return std::vector<bool> const&
 */
std::vector<bool> const &getTiles() const;

• Brak komendy
  Szczegółowy opis danego fragmentu kodu nie musi być poprzedzony żadną komendą. Nie każdy fragment kodu wymaga szczegółowego opisu - w wielu przypadkach wystarczy krótki opis poprzedzony komendą @brief

/**
 * @brief Construct a new Executor object.
 * The Turtle is stored as a reference and will be modified.
 * Appropriate lifetime for the Turtle needs to be ensured.
 *
 * @param code the code
 * @param turtle reference to a Turtle
 */
Executor(std::vector<std::vector<Cmd>> code, Turtle &turtle);

Doxygen - jak wygenerować dokumentację

0. Utwórz folder Docs, w którym zostanie umieszczona wygenerowana dokumentacja
1. Uruchom program Doxywizard
2. Wybierz katalog z kodem źródłowym programu

W tym momencie zalecam zapisanie wstępnie wygenerowanych ustawień Doxygena, aby zapobiec pewnym bugom (np. przy wyborze ścieżki kodu źródłowego)

3. Skonfiguruj pierwszą zakładkę - Project. Zalecam zaznaczenie opcji Scan recursively przy wyborze katalogu z kodem źródłowym

Zarówno ścieżka katalogu z kodem źródłowym, jak i katalogu docelowego, powinny być ścieżkami relatywnymi do katalogu podanego w kroku drugim (podobnie jak na screenshocie). Jeśli widzisz pełną ścieżkę, która zaczyna się od twojej litery dysku, powinieneś to poprawić

4. W drugiej zakładce - Mode - prawdopodobnie nie musisz niczego zmieniać

5. Skonfiguruj trzecią zakładkę - Output. Polecam jedynie zmienić tryb HTML z plain HTML na with navigation panel

6. Skonfiguruj ostatnią zakładkę - Diagrams. Aby otrzymać ciekawe grafy wywołań, polecam zaznaczyć wszystkie rodzaje grafów do wygenerowania

7. Opcjonalnie - zmień ustawienia w kategorii Expert -> Build. Zaznacz te opcje, co na poniższym screenie. Spowoduje to, że zostanie wygenerowana dokumentacja dla prywatnych członków klas/struktur, metod statycznych, a także anonimowych przestrzenii nazw

8. Zapisz skonfigurowany plik Doxyfile i wygeneruj dokumentację

Po wygenerowaniu dokumentacji od razu możesz przeglądać dokumentację w formacie HTML (otwórz plik index.html), ale dokumentacja w formie pliku PDF wciąż wymaga zbudowania programem TeX. Jeśli zainstalowałeś TeXa poprawnie, możesz uruchomić plik make.bat znajdujący się w katalogu latex.

Pierwsze uruchomienie pliku make.bat potrwa długo, ponieważ MiKTeX musi pobrać wymagane pakiety. Jeśli dokumentacja wygenerowała się poprawnie - gratuluję! Jeśli wystąpi taki lub podobny błąd:

Oznacza to, że używasz znaków niewspieranych przez pdflatex. Najprostszym rozwiązaniem jest usunięcie niedozwolonych znaków z dokumentacji.

Wygeneruj dokumentację ponownie i odpal plik make.bat. Jeśli wszystko pójdzie OK, wygenerujesz dokumentację w formacie PDF. Plik wyjściowy nazywa się refman.pdf

Przejrzyj wygenerowany plik. Sprawdź, czy jest hiperlinkowany (posiada linki, które można kliknąć, aby przejść do innego miejsca w dokumentacji). Sprawdź, czy została wygenerowana dokumentacja dla wszystkich fragmentów kodu, dla których miała zostać wygenerowana. Sprawdź, czy wygląda poprawnie

Wzór sprawozdania - edycja plików TeX

W serwisie Moodle dostępny jest wzór sprawozdania w formacie .tex. Wystarczy dopasować go do swojego programu i skompilować z użyciem komendy pdflatex

0. Zainstaluj edytor Visual Studio Code i doinstaluj plugin LaTeX Workshop. Wymagana jest także instalacja Perla. Znacznie ułatwi ci to edycję pliku TeX, a także umożliwi kompilację do pliku PDF poprzez kliknięcie przycisku
1. Polecam zmienić nazwę dołączonego pliku PDF. W ten sposób nie zostanie on nadpisany i posłuży za wzór, do którego będziecie mogli porównywać swoje sprawozdanie

2. Otwórz plik sprawozdanie.tex w dowolnym edytorze tekstu. Rekomenduję oczywiście VS Code z pluginem LaTeX Workshop

4. Modyfikuj sprawozdanie, aby dopasować je do swoich potrzeb

5. Kompiluj regularnie swoje sprawozdanie i sprawdzaj, czy wygląda poprawnie. W przypadku VS Code jest od tego przycisk

Użytkownicy edytorów tekstu nie wspierających LaTeXa muszą skompilować swoje sprawozdanie z wiersza poleceń

Efekt powyższej edycji:

6. W trakcie pisania usuwaj fragmenty typu \marginpar{Dokładny opis zadania, zgodny z tematem podanym przez prowadzącego.}, gdyż są one jedynie poradą dla ciebie i nie powinny znaleźć się w gotowym sprawozdaniu

Kod C++ w pliku TeX

Poprawne wyświetlanie kodu C++ w pliku TeX wymaga użycia komendy \lstinline[language=C++], na przykład \lstinline[language=C++]|std::size_t|. Są też inne przydatne komendy, znajdziesz je we wzorze sprawozdania. Zawsze, gdy musisz odpowiednio sformatować fragment tekstu lub np. umieścić obrazek w sprawozdaniu, zobacz, jak to jest zrobione we wzorze i zrób podobnie.

Prawa autorskie

Copyright 2022 DarkoGNU
Licensed under GFDL-1.3-or-later