doxygen_manual-1.8.1 (1035109), страница 40
Текст из файла (страница 40)
The result of parsing a tag file is the insertion of Entry objects in the entry tree. Thefield Entry::tagInfo is used to mark the entry as external, and holds information about the tag file.Documentation parserSpecial comment blocks are stored as strings in the entities that they document. There is a string for the briefdescription and a string for the detailed description. The documentation parser reads these strings and executesthe commands it finds in it (this is the second pass in parsing the documentation).
It writes the result directly to theoutput generators.The parser is written in C++ and can be found in src/docparser.cpp. The tokens that are eaten by the parser comefrom src/doctokenizer.l. Code fragments found in the comment blocks are passed on to the source parser.The main entry point for the documentation parser is validatingParseDoc() declared in src/docparser.h. For simple texts with special commands validatingParseText() is used.Source parserIf source browsing is enabled or if code fragments are encountered in the documentation, the source parser isinvoked.The code parser tries to cross-reference to source code it parses with documented entities.
It also does syntaxhighlighting of the sources. The output is directly written to the output generators.The main entry point for the code parser is parseCode() declared in src/code.h.Output generatorsAfter data is gathered and cross-referenced, doxygen generates output in various formats. For this it uses themethods provided by the abstract class OutputGenerator. In order to generate output for multiple formats atonce, the methods of OutputList are called instead. This class maintains a list of concrete output generators,where each method called is delegated to all generators in the list.To allow small deviations in what is written to the output for each concrete output generator, it is possible to temporarily disable certain generators. The OutputList class contains various disable() and enable() methodsfor this.
The methods OutputList::pushGeneratorState() and OutputList::popGeneratorState() are used to temporarily save the set of enabled/disabled output generators on a stack.The XML is generated directly from the gathered data structures. In the future XML will be used as an intermediatelanguage (IL). The output generators will then use this IL as a starting point to generate the specific output formats.The advantage of having an IL is that various independently developed tools written in various languages, couldextract information from the XML output. Possible tools could be:• an interactive source browser• a class diagram generator• computing code metrics.Generated by Doxygen168Doxygen’s internalsDebuggingSince doxygen uses a lot of flex code it is important to understand how flex works (for this one should readthe man page) and to understand what it is doing when flex is parsing some input.
Fortunately, when flex is usedwith the -d option it outputs what rules matched. This makes it quite easy to follow what is going on for a particularinput fragment.To make it easier to toggle debug information for a given flex file I wrote the following perl script, which automaticallyadds or removes -d from the correct line in the Makefile:#!/usr/bin/perl$file = shift @ARGV;print "Toggle debugging mode for $file\n";# add or remove the -d flex flag in the makefileunless (rename "Makefile.libdoxygen","Makefile.libdoxygen.old") {print STDERR "Error: cannot rename Makefile.libdoxygen!\n";exit 1;}if (open(F,"<Makefile.libdoxygen.old")) {unless (open(G,">Makefile.libdoxygen")) {print STDERR "Error: opening file Makefile.libdoxygen for writing\n";exit 1;}print "Processing Makefile.libdoxygen...\n";while (<F>) {if ( s/(LEX) (-i )?-P([a-zA-Z]+)YY -t $file/(LEX) -d \1-P\2YY -t $file/g ) {print "Enabling debug info for $file\n";}elsif ( s/(LEX) -d (-i )?-P([a-zA-Z]+)YY -t $file/(LEX) \1-P\2YY -t $file/g ) {print "Disabling debug info for $file\n";}print G "$_";}close F;unlink "Makefile.libdoxygen.old";}else {print STDERR "Warning file Makefile.libdoxygen.old does not exist!\n";}# touch the file$now = time;utime $now, $now, $fileGenerated by DoxygenChapter 25Perl Module Output formatSince version 1.2.18, Doxygen can generate a new output format we have called the "Perl Module output format".It has been designed as an intermediate format that can be used to generate new and customized output withouthaving to modify the Doxygen source.
Therefore, its purpose is similar to the XML output format that can be alsogenerated by Doxygen. The XML output format is more standard, but the Perl Module output format is possiblysimpler and easier to use.The Perl Module output format is still experimental at the moment and could be changed in incompatible waysin future versions, although this should not be very probable. It is also lacking some features of other Doxygenbackends. However, it can be already used to generate useful output, as shown by the Perl Module-based LaTeXgenerator.Please report any bugs or problems you find in the Perl Module backend or the Perl Module-based LaTeX generatorto the doxygen-develop mailing list. Suggestions are welcome as well.25.1UsageWhen the GENERATE_PERLMOD tag is enabled in the Doxyfile, running Doxygen generates a number of files inthe perlmod/ subdirectory of your output directory.
These files are the following:• DoxyDocs.pm. This is the Perl module that actually contains the documentation, in the Perl Module formatdescribed below.• DoxyModel.pm. This Perl module describes the structure of DoxyDocs.pm, independently of the actualdocumentation. See below for details.• doxyrules.make. This file contains the make rules to build and clean the files that are generated from theDoxyfile. Also contains the paths to those files and other relevant information. This file is intended to beincluded by your own Makefile.• Makefile. This is a simple Makefile including doxyrules.make.To make use of the documentation stored in DoxyDocs.pm you can use one of the default Perl Module-basedgenerators provided by Doxygen (at the moment this includes the Perl Module-based LaTeX generator, see below)or write your own customized generator.
This should not be too hard if you have some knowledge of Perl and it’sthe main purpose of including the Perl Module backend in Doxygen. See below for details on how to do this.25.2Using the LaTeX generator.The Perl Module-based LaTeX generator is pretty experimental and incomplete at the moment, but you could findit useful nevertheless. It can generate documentation for functions, typedefs and variables within files and classes170Perl Module Output formatand can be customized quite a lot by redefining TeX macros.
However, there is still no documentation on how to dothis.Setting the PERLMOD_LATEX tag to YES in the Doxyfile enables the creation of some additional files in theperlmod/ subdirectory of your output directory. These files contain the Perl scripts and LaTeX code necessary togenerate PDF and DVI output from the Perl Module output, using PDFLaTeX and LaTeX respectively. Rules toautomate the use of these files are also added to doxyrules.make and the Makefile.The additional generated files are the following:• doxylatex.pl. This Perl script uses DoxyDocs.pm and DoxyModel.pm to generate doxydocs.tex, a TeXfile containing the documentation in a format that can be accessed by LaTeX code.
This file is not directlyLaTeXable.• doxyformat.tex. This file contains the LaTeX code that transforms the documentation from doxydocs.tex intoLaTeX text suitable to be LaTeX’ed and presented to the user.• doxylatex-template.pl. This Perl script uses DoxyModel.pm to generate doxytemplate.tex, a TeX file defining default values for some macros. doxytemplate.tex is included by doxyformat.tex to avoid the need ofexplicitly defining some macros.• doxylatex.tex. This is a very simple LaTeX document that loads some packages and includes doxyformat.texand doxydocs.tex.
This document is LaTeX’ed to produce the PDF and DVI documentation by the rules addedto doxyrules.make.25.2.1Creation of PDF and DVI outputTo try this you need to have installed LaTeX, PDFLaTeX and the packages used by doxylatex.tex.1. Update your Doxyfile to the latest version using:doxygen -u Doxyfile2.
Set both GENERATE_PERLMOD and PERLMOD_LATEX tags to YES in your Doxyfile.3. Run Doxygen on your Doxyfile:doxygen Doxyfile4. A perlmod/ subdirectory should have appeared in your output directory. Enter the perlmod/ subdirectory andrun:make pdfThis should generate a doxylatex.pdf with the documentation in PDF format.5. Run:make dviThis should generate a doxylatex.dvi with the documentation in DVI format.Generated by Doxygen25.3 Documentation format.25.3171Documentation format.The Perl Module documentation generated by Doxygen is stored in DoxyDocs.pm. This is a very simple Perl module that contains only two statements: an assignment to the variable $doxydocs and the customary 1; statementwhich usually ends Perl modules.
The documentation is stored in the variable $doxydocs, which can then beaccessed by a Perl script using DoxyDocs.pm.$doxydocs contains a tree-like structure composed of three types of nodes: strings, hashes and lists.• Strings. These are normal Perl strings. They can be of any length can contain any character. Their semanticsdepends on their location within the tree. This type of node has no children.• Hashes.
These are references to anonymous Perl hashes. A hash can have multiple fields, each with adifferent key. The value of a hash field can be a string, a hash or a list, and its semantics depends on the keyof the hash field and the location of the hash within the tree. The values of the hash fields are the children ofthe node.• Lists. These are references to anonymous Perl lists. A list has an undefined number of elements, whichare the children of the node. Each element has the same type (string, hash or list) and the same semantics,depending on the location of the list within the tree.As you can see, the documentation contained in $doxydocs does not present any special impediment to be processed by a simple Perl script.25.4Data structureYou might be interested in processing the documentation contained in DoxyDocs.pm without needing to take intoaccount the semantics of each node of the documentation tree.
![](https://s.studizba.com/z.php?f=/templates/si/i/noavatar.png&w=100&h=100&t=1"){kind=avatar}
