Doxygen
 | |
 | |
| Deweloperzy | Dimitri van Heesch |
|---|---|
| Pierwsze wydanie | 26 października 1997 |
| Wersja stabilna | 1.9.6 / 27 grudnia 2022
|
| Magazyn | |
| Napisane w | C++ |
| System operacyjny | Międzyplatformowe |
| Typ | Generator dokumentacji |
| Licencja | GPLv2 |
| Strona internetowa | doxygen.nl |
Doxygen ( / drzew d ɒ k s i dʒ ən / DOK -see-jən ) to generator dokumentacji i narzędzie do analizy statycznej źródłowych oprogramowania . Używany jako generator dokumentacji, Doxygen wydobywa informacje ze specjalnie sformatowanych komentarzy w kodzie. Gdy jest używany do analizy, Doxygen wykorzystuje swoje drzewo analizy do generowania diagramów i wykresów struktury kodu. Doxygen może krzyżować dokumentację i kod odniesienia, dzięki czemu czytelnik dokumentu może łatwo odnieść się do rzeczywistego kodu.
Doxygen jest wolnym oprogramowaniem , wydanym na warunkach Powszechnej Licencji Publicznej GNU w wersji 2 (GPLv2).
Projekt
Podobnie jak Javadoc , Doxygen wyodrębnia dokumentację z komentarzy do plików źródłowych. Oprócz składni Javadoc, Doxygen obsługuje znaczniki dokumentacji używane w zestawie narzędzi Qt i może generować dane wyjściowe w HyperText Markup Language ( HTML ), jak również w Microsoft Compiled HTML Help (CHM), Rich Text Format (RTF), Portable Document Format (PDF), LaTeX , PostScript lub strony podręcznika .
Używa
Języki programowania obsługiwane przez Doxygen to C , C++ , C# , D , Fortran , IDL , Java , Objective-C , Perl , PHP , Python i VHDL . Inne języki mogą być obsługiwane za pomocą dodatkowego kodu.
Doxygen działa na większości systemów uniksopodobnych , macOS i Windows .
Pierwsza wersja Doxygen zapożyczyła kod z wczesnej wersji DOC++, opracowanej przez Rolanda Wunderlinga i Malte Zöckler z Zuse Institute Berlin . Później kod Doxygen został przepisany przez Dimitri van Heesch.
Doxygen ma wbudowaną obsługę generowania diagramów dziedziczenia dla klas C++. Aby uzyskać bardziej zaawansowane diagramy i wykresy, Doxygen może użyć narzędzia „kropka” z Graphviz .
Przykładowy kod
Ogólna składnia komentarzy do dokumentacji polega na rozpoczynaniu komentarza od dodatkowej gwiazdki po wiodącym ograniczniku komentarza „/*”:
/** < Krótki jednolinijkowy opis> <Dłuższy opis> <W razie potrzeby może obejmować wiele linii lub akapitów> @param Opis parametru wejściowego metody lub funkcji @param ... @return Opis zwracanej wartości */
Wielu programistów lubi oznaczać początek każdej linii spacją-gwiazdką-spacją w następujący sposób, ale nie jest to konieczne.
/** * < Krótki jednolinijkowy opis> * * <Dłuższy opis> * <Może obejmować wiele wierszy lub akapitów w razie potrzeby> * * @param Opis parametru wejściowego metody lub funkcji * @param ... * @return Opis zwracana wartość */
Wielu programistów unika używania komentarzy w stylu C i zamiast tego używa komentarzy jednowierszowych w stylu C++. Doxygen akceptuje komentarze z dodatkowym ukośnikiem jako komentarze Doxygen.
/// <Krótki jednolinijkowy opis> /// /// <Dłuższy opis> /// <W razie potrzeby może obejmować wiele linii lub akapitów> /// /// @param Opis parametru wejściowego metody lub funkcji // / @param ... /// @return Opis zwracanej wartości
Poniżej przedstawiono sposób udokumentowania pliku źródłowego języka C++ .
/** * @plik * @autor John Doe <[email protected]> * @wersja 1.0 * * @sekcja LICENCJA * * Ten program jest wolnym oprogramowaniem; możesz go redystrybuować i/lub * modyfikować zgodnie z warunkami Powszechnej Licencji Publicznej GNU, * opublikowanej przez Free Software Foundation; albo wersję 2 * Licencji, albo (według własnego uznania) dowolną nowszą wersję. * * Ten program jest rozpowszechniany w nadziei, że będzie użyteczny, ale * BEZ JAKIEJKOLWIEK GWARANCJI; nawet bez domniemanej gwarancji * PRZYDATNOŚCI HANDLOWEJ lub PRZYDATNOŚCI DO OKREŚLONEGO CELU. Zobacz GNU * General Public License, aby uzyskać więcej informacji na * https://www.gnu.org/copyleft/gpl.html * * @section OPIS * * Klasa time reprezentuje chwilę czasu. */ class Time { public : /** * Konstruktor ustawiający czas na zadaną wartość. * * @param timemillis to liczba milisekund *, które upłynęły od 1 stycznia 1970 r. */ Czas ( int timemillis ) { // kod } /** * Pobierz aktualny czas. * * @return Obiekt czasu ustawiony na bieżący czas. */ static Czas teraz () { // kod } };
Poniżej przedstawiono alternatywne podejście do dokumentowania parametrów. Spowoduje to utworzenie tej samej dokumentacji.
/** * Konstruktor ustawiający czas na określoną wartość. */ Czas ( int timemillis ///< Liczba milisekund, które upłynęły od 1 stycznia 1970 r.> ) { // kod }
Bogatsze znaczniki są również możliwe. Na przykład dodaj równania za pomocą poleceń LaTeX :
/** * * Równanie wbudowane @f$ e^{\pi i}+1 = 0 @f$ * * Równanie wyświetlane: @f[ e^{\pi i}+1 = 0 @f] * * /
Źródło i rozwój Doxygen
Źródła Doxygen są obecnie hostowane na GitHub , gdzie główny programista, Dimitri van Heesch, współtworzy pod nazwą użytkownika „doxygen”. Doxygen jest napisany w C++ i składa się z około 300 000 linii źródłowych kodu . Do analizy leksykalnej standardowe narzędzie Lex (lub jego zamiennik Flex) jest uruchamiane przez około 35 000 linii skryptu lex. Używane jest również narzędzie parsujące Yacc (lub jego zamiennik Bison), ale tylko do mniejszych zadań ; większość analizowania języka jest wykonywana przez natywny kod C++. Proces kompilacji jest oparty na CMake i obejmuje również niektóre skrypty Pythona.
