Doxygen - Doxygen
Deweloper(zy) | Dimitri van Heesch |
---|---|
Pierwsze wydanie | 26 października 1997 |
Wersja stabilna | 1.9.1 / 8 stycznia 2021 r
|
Magazyn | |
Napisane w | C++ |
System operacyjny | Wieloplatformowy |
Rodzaj | Generator dokumentacji |
Licencja | GPLv2 |
Stronie internetowej | www |
Doxygen ( / d ɒ k s i dʒ ən / DOK -patrz-jən ) jest generator dokumentacja i analiza statyczna narzędziem oprogramowanie drzew źródłowych . Używany jako generator dokumentacji, Doxygen wyodrębnia informacje ze specjalnie sformatowanych komentarzy w kodzie. W przypadku użycia do analizy, Doxygen używa swojego drzewa parsowania do generowania diagramów i wykresów struktury kodu. Doxygen może odwoływać się do dokumentacji i kodu, 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 języku HyperText Markup Language ( HTML ), a także w Microsoft Compiled HTML Help (CHM), Rich Text Format (RTF), Portable Document Format (PDF), LaTeX , PostScript lub strony podręcznika .
Zastosowania
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 Doxygena zapożyczyła kod z wczesnej wersji DOC++, opracowanej przez Rolanda Wunderlinga i Malte Zöcklera w 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++. W przypadku bardziej zaawansowanych diagramów i wykresów Doxygen może użyć narzędzia „kropka” z Graphviz .
Przykładowy kod
Ogólna składnia komentarzy dokumentacji polega na rozpoczynaniu komentarza dodatkową gwiazdką po wiodącym ograniczniku komentarza '/*':
/**
<A short one line description>
<Longer description>
<May span multiple lines or paragraphs as needed>
@param Description of method's or function's input parameter
@param ...
@return Description of the return value
*/
Wielu programistów lubi oznaczać początek każdej linii spacją-gwiazdką-spacją, ale nie jest to konieczne.
/**
* <A short one line description>
*
* <Longer description>
* <May span multiple lines or paragraphs as needed>
*
* @param Description of method's or function's input parameter
* @param ...
* @return Description of the return value
*/
Wielu programistów unika używania komentarzy w stylu C i zamiast tego używa jednowierszowych komentarzy w stylu C++. Doxygen akceptuje komentarze z dodatkowym ukośnikiem jako komentarze Doxygen.
/// <A short one line description>
///
/// <Longer description>
/// <May span multiple lines or paragraphs as needed>
///
/// @param Description of method's or function's input parameter
/// @param ...
/// @return Description of the return value
Poniżej przedstawiono sposób dokumentowania pliku źródłowego C++ .
/**
* @file
* @author John Doe <jdoe@example.com>
* @version 1.0
*
* @section LICENSE
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
* published by the Free Software Foundation; either version 2 of
* the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details at
* https://www.gnu.org/copyleft/gpl.html
*
* @section DESCRIPTION
*
* The time class represents a moment of time.
*/
class Time {
public:
/**
* Constructor that sets the time to a given value.
*
* @param timemillis is a number of milliseconds
* passed since Jan 1, 1970.
*/
Time (int timemillis) {
// the code
}
/**
* Get the current time.
*
* @return A time object set to the current time.
*/
static Time now () {
// the code
}
};
Poniżej przedstawiono alternatywne podejście do dokumentowania parametrów. Stworzy taką samą dokumentację.
/**
* Constructor that sets the time to a given value.
*/
Time (int timemillis ///< Number of milliseconds passed since Jan 1, 1970.>
)
{
// the code
}
Możliwy jest również bogatszy znacznik. Na przykład dodaj równania za pomocą poleceń LaTeX :
/**
*
* An inline equation @f$ e^{\pi i}+1 = 0 @f$
*
* A displayed equation: @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, działa pod nazwą użytkownika „doxygen”. Doxygen jest napisany w C++ i składa się z około 300 000 linii kodu źródłowego . Do analizy leksykalnej standardowe narzędzie Lex (lub zastępujące go Flex) jest uruchamiane przez około 35 000 wierszy skryptu leksykalnego . Analizowania narzędzie Yacc (lub jej zamiennik Bison) jest również stosowany, ale tylko dla drobnych zadań; większość parsowania języka jest wykonywana przez natywny kod C++. Proces budowania jest oparty na CMake i obejmuje również niektóre skrypty Pythona.