doxygen_manual-1.8.1 (1035109), страница 39
Текст из файла (страница 39)
Similar to using <tt>text</tt>.• <code> Set one or more lines of source code or program output. Note that this command behaves like\code ... \endcode for C# code, but it behaves like the HTML equivalent <code>...</code>for other languages.• <description> Part of a <list> command, describes an item.• <example> Marks a block of text as an example, ignored by doxygen.• <exception cref="member"> Identifies the exception a method can throw.• <include> Can be used to import a piece of XML from an external file. Ignored by doxygen at the moment.• <inheritdoc> Can be used to insert the documentation of a member of a base class into the documentation of a member of a derived class that reimplements it.• <item> List item.
Can only be used inside a <list> context.• <list type="type"> Starts a list, supported types are bullet or number and table. A list consists of a number of <item> tags. A list of type table, is a two column table which can have a header.• <listheader> Starts the header of a list of type "table".• <para> Identifies a paragraph of text.• <param name="paramName"> Marks a piece of text as the documentation for parameter "paramName". Similar to using \param.• <paramref name="paramName"> Refers to a parameter with name "paramName". Similar to using\a.• <permission> Identifies the security accessibility of a member. Ignored by doxygen.• <remarks> Identifies the detailed description.• <returns> Marks a piece of text as the return value of a function or method. Similar to using \return.• <see cref="member"> Refers to a member.
Similar to \ref.• <seealso cref="member"> Starts a "See also" section referring to "member". Similar to using \samember.162XML commands• <summary> Identifies the brief description. Similar to using \brief.• <term> Part of a <list> command.• <typeparam name="paramName"> Marks a piece of text as the documentation for type parameter"paramName". Similar to using \param.• <typeparamref name="paramName"> Refers to a parameter with name "paramName". Similar tousing \a.• <value> Identifies a property. Ignored by doxygen.Here is an example of a typical piece of code using some of the above commands:\textcolor{comment}{/// <summary>}\textcolor{comment}{}\textcolor{comment}{/// A search engine.}\textcolor{comment}{}\textcolor{comment}{/// </summary>}\textcolor{comment}{}\textcolor{keyword}{class }Engine\{\textcolor{comment}{}\textcolor{comment}{ /// <summary>}\textcolor{comment}{ /// The Search method takes a series of parameters to specify the searchcriterion}\textcolor{comment}{ /// and returns a dataset containing the result set.}\textcolor{comment}{ /// </summary>}\textcolor{comment}{ /// <param name="connectionString">the connection string to connect to the}\textcolor{comment}{ /// database holding the content to search</param>}\textcolor{comment}{ /// <param name="maxRows">The maximum number of rows to}\textcolor{comment}{ /// return in the result set</param>}\textcolor{comment}{ /// <param name="searchString">The text that we are searching for</param>}\textcolor{comment}{ /// <returns>A DataSet instance containing the matching rows.
It contains amaximum}\textcolor{comment}{ /// number of rows specified by the maxRows parameter</returns>}\textcolor{comment}{} \textcolor{keyword}{public} DataSet Search(\textcolor{keywordtype}{string} connectionSt\{DataSet ds = \textcolor{keyword}{new} DataSet();\textcolor{keywordflow}{return} ds;\}\}Generated by DoxygenPart IIIDevelopers ManualChapter 24Doxygen’s internalsDoxygen’s internalsNote that this section is still under construction!The following picture shows how source files are processed by doxygen.config fileConfig parserXMLget settingsHTMLinput filesdrivesC PreprocessorLanguage parserinputstringData organiserOutput generatorsentrytreeLaTeXRTFentrytreedrivesdrivesManDoc Parsertag file parserdrivesSource ParserdrivesFigure 24.1: Data flow overviewThe following sections explain the steps above in more detail.Config parserThe configuration file that controls the settings of a project is parsed and the settings are stored in the singletonclass Config in src/config.h.
The parser itself is written using flex and can be found in src/config.l.This parser is also used directly by doxywizard, so it is put in a separate library.Each configuration option has one of 5 possible types: String, List, Enum, Int, or Bool. The values of these166Doxygen’s internalsoptions are available through the global functions Config_getXXX(), where XXX is the type of the option.The argument of these function is a string naming the option as it appears in the configuration file. For instance:Config_getBool("GENERATE_TESTLIST") returns a reference to a boolean value that is TRUE if the test listwas enabled in the config file.The function readConfiguration() in src/doxygen.cpp reads the command line options and then callsthe configuration parser.C PreprocessorThe input files mentioned in the config file are (by default) fed to the C Preprocessor (after being piped through auser defined filter if available).The way the preprocessor works differs somewhat from a standard C Preprocessor.
By default it does not do macroexpansion, although it can be configured to expand all macros. Typical usage is to only expand a user specified setof macros. This is to allow macro names to appear in the type of function parameters for instance.Another difference is that the preprocessor parses, but not actually includes code when it encounters a #include(with the exception of #include found inside { ... } blocks).
The reasons behind this deviation from the standard isto prevent feeding multiple definitions of the same functions/classes to doxygen’s parser. If all source files wouldinclude a common header file for instance, the class and type definitions (and their documentation) would be presentin each translation unit.The preprocessor is written using flex and can be found in src/pre.l. For condition blocks (#if) evaluation ofconstant expressions is needed.
For this a yacc based parser is used, which can be found in src/constexp.yand src/constexp.l.The preprocessor is invoked for each file using the preprocessFile() function declared in src/pre.h, andwill append the preprocessed result to a character buffer. The format of the character buffer is0x060x06...0x060x06file name 1preprocessed contents of file 1file name npreprocessed contents of file nLanguage parserThe preprocessed input buffer is fed to the language parser, which is implemented as a big state machine usingflex. It can be found in the file src/scanner.l.
There is one parser for all languages (C/C++/Java/IDL). Thestate variables insideIDL and insideJava are uses at some places for language specific choices.The task of the parser is to convert the input buffer into a tree of entries (basically an abstract syntax tree). An entryis defined in src/entry.h and is a blob of loosely structured information. The most important field is sectionwhich specifies the kind of information contained in the entry.Possible improvements for future versions:• Use one scanner/parser per language instead of one big scanner.• Move the first pass parsing of documentation blocks to a separate module.• Parse defines (these are currently gathered by the preprocessor, and ignored by the language parser).Data organizerThis step consists of many smaller steps, that build dictionaries of the extracted classes, files, namespaces, variables, functions, packages, pages, and groups.
Besides building dictionaries, during this step relations (such asinheritance relations), between the extracted entities are computed.Each step has a function defined in src/doxygen.cpp, which operates on the tree of entries, built duringlanguage parsing. Look at the "Gathering information" part of parseInput() for details.Generated by Doxygen167The result of this step is a number of dictionaries, which can be found in the Doxygen "namespace" defined insrc/doxygen.h. Most elements of these dictionaries are derived from the class Definition; The classMemberDef, for instance, holds all information for a member.
An instance of such a class can be part of a file (class FileDef ), a class ( class ClassDef ), a namespace ( class NamespaceDef ), a group ( class GroupDef ), or a Java package ( class PackageDef ).Tag file parserIf tag files are specified in the configuration file, these are parsed by a SAX based XML parser, which can be foundin src/tagreader.cpp.
![](https://s.studizba.com/z.php?f=/templates/si/i/noavatar.png&w=100&h=100&t=1"){kind=avatar}
