doxygen_manual-1.8.1 (Методичка, задание и документация на ЛР №7), страница 7

If you do not have a PostScript printer, you can try to use ghostscript to convert PostScript intosomething your printer understands.Conversion to PDF is also possible if you have installed the ghostscript interpreter; just type make pdf (or makepdf_2on1).To get the best results for PDF output you should set the PDF_HYPERLINKS and USE_PDFLATEX tags to YES.In this case the Makefile will only contain a target to build refman.pdf directly.2.3.3RTF outputDoxygen combines the RTF output to a single file called refman.rtf.

This file is optimized for importing into theMicrosoft Word. Certain information is encoded using so called fields. To show the actual value you need to selectall (Edit - select all) and then toggle fields (right click and select the option from the drop down menu).2.3.4XML outputThe XML output consists of a structured "dump" of the information gathered by doxygen.

Each compound (class/namespace/file/...) has its own XML file and there is also an index file called index.xml.A file called combine.xslt XSLT script is also generated and can be used to combine all XML files into a singlefile.Doxygen also generates two XML schema files index.xsd (for the index file) and compound.xsd (for thecompound files). This schema file describes the possible elements, their attributes and how they are structured, i.e.it the describes the grammar of the XML files and can be used for validation or to steer XSLT scripts.In the addon/doxmlparser directory you can find a parser library for reading the XML output produced bydoxygen in an incremental way (see addon/doxmlparser/include/doxmlintf.h for the interface of thelibrary)2.3.5Man page outputThe generated man pages can be viewed using the man program.

You do need to make sure the man directory isin the man path (see the MANPATH environment variable). Note that there are some limitations to the capabilitiesof the man page format, so some information (like class diagrams, cross references and formulas) will be lost.Generated by Doxygen2.4 Step 3: Documenting the sources2.417Step 3: Documenting the sourcesAlthough documenting the sources is presented as step 3, in a new project this should of course be step 1.

Here Iassume you already have some code and you want doxygen to generate a nice document describing the API andmaybe the internals and some related design documentation as well.If the EXTRACT_ALL option is set to NO in the configuration file (the default), then doxygen will only generatedocumentation for documented entities. So how do you document these? For members, classes and namespacesthere are basically two options:1. Place a special documentation block in front of the declaration or definition of the member, class or namespace. For file, class and namespace members it is also allowed to place the documentation directly after themember.See section Special comment blocks to learn more about special documentation blocks.2. Place a special documentation block somewhere else (another file or another location) and put a structuralcommand in the documentation block.

A structural command links a documentation block to a certain entitythat can be documented (e.g. a member, class, namespace or file).See section Documentation at other places to learn more about structural commands.The advantage of the first option is that you do not have to repeat the name of the entity.Files can only be documented using the second option, since there is no way to put a documentation block beforea file.

Of course, file members (functions, variables, typedefs, defines) do not need an explicit structural command;just putting a special documentation block in front or behind them will work fine.The text inside a special documentation block is parsed before it is written to the HTML and/or LATEX output files.During parsing the following steps take place:• Markdown formatting is replaced by corresponding HTML or special commands.• The special commands inside the documentation are executed. See section Special Commands for anoverview of all commands.• If a line starts with some whitespace followed by one or more asterisks (∗) and then optionally more whitespace, then all whitespace and asterisks are removed.• All resulting blank lines are treated as a paragraph separators.

This saves you from placing new-paragraphcommands yourself in order to make the generated documentation readable.• Links are created for words corresponding to documented classes (unless the word is preceded by a %; thenthe word will not be linked and the % sign is removed).• Links to members are created when certain patterns are found in the text.

See section Automatic link generation for more information on how the automatic link generation works.• HTML tags that are in the documentation are interpreted and converted to LATEX equivalents for the LATEXoutput. See section HTML Commands for an overview of all supported HTML tags.Generated by Doxygen18Getting StartedGenerated by DoxygenChapter 3Documenting the codeThis chapter covers two topics:1. How to put comments in your code such that doxygen incorporates them in the documentation it generates.This is further detailed in the next section.2. Ways to structure the contents of a comment block such that the output looks good, as explained in sectionAnatomy of a comment block.3.1Special comment blocksA special comment block is a C or C++ style comment block with some additional markings, so doxygen knows itis a piece of structured text that needs to end up in the generated documentation.

The next section presents thevarious styles supported by doxygen.For Python, VHDL, Fortran, and Tcl code there are different commenting conventions, which can be found in sections Comment blocks in Python, Comment blocks in VHDL, Comment blocks in Fortran, and Comment blocks inTcl respectively.3.1.1Comment blocks for C-like languages (C/C++/C#/Objective-C/PHP/Java)For each entity in the code there are two (or in some cases three) types of descriptions, which together formthe documentation for that entity; a brief description and detailed description, both are optional. For methodsand functions there is also a third type of description, the so called in body description, which consists of theconcatenation of all comment blocks found within the body of the method or function.Having more than one brief or detailed description is allowed (but not recommended, as the order in which thedescriptions will appear is not specified).As the name suggest, a brief description is a short one-liner, whereas the detailed description provides longer, moredetailed documentation.

An "in body" description can also act as a detailed description or can describe a collectionof implementation details. For the HTML output brief descriptions are also used to provide tooltips at places wherean item is referenced.There are several ways to mark a comment block as a detailed description:1. You can use the JavaDoc style, which consist of a C-style comment block starting with two ∗’s, like this:/*** ... text ...*/2.

or you can use the Qt style and add an exclamation mark (!) after the opening of a C-style comment block,as shown in this example:20Documenting the code/*!* ... text ...*/In both cases the intermediate ∗’s are optional, so/*!... text ...*/is also valid.3. A third alternative is to use a block of at least two C++ comment lines, where each line starts with an additionalslash or an exclamation mark. Here are examples of the two cases:////// ... text ...///or//!//!... text ...//!Note that a blank line ends a documentation block in this case.4.

Some people like to make their comment blocks more visible in the documentation. For this purpose you canuse the following:/********************************************//*** ... text***********************************************/(note the 2 slashes to end the normal comment block and start a special comment block).or//////////////////////////////////////////////////// ... text .../////////////////////////////////////////////////For the brief description there are also several possibilities:1.

One could use the \brief command with one of the above comment blocks. This command ends at the end ofa paragraph, so the detailed description follows after an empty line.Here is an example:/*! \brief Brief description.Brief description continued.*** Detailed description starts here.*/2.

If JAVADOC_AUTOBRIEF is set to YES in the configuration file, then using JavaDoc style comment blockswill automatically start a brief description which ends at the first dot followed by a space or new line. Here isan example:/** Brief description which ends at this dot. Details follow* here.*/The option has the same effect for multi-line special C++ comments:Generated by Doxygen3.1 Special comment blocks21/// Brief description which ends at this dot. Details follow/// here.3. A third option is to use a special C++ style comment which does not span more than one line.

Here are twoexamples:/// Brief description./** Detailed description. */or//! Brief description.//! Detailed description//! starts here.Note the blank line in the last example, which is required to separate the brief description from the blockcontaining the detailed description. The JAVADOC_AUTOBRIEF should also be set to NO for this case.As you can see doxygen is quite flexible.

If you have multiple detailed descriptions, like in the following example://! Brief description, which is//! really a detailed description since it spans multiple lines./*! Another detailed description!*/They will be joined. Note that this is also the case if the descriptions are at different places in the code! In this casethe order will depend on the order in which doxygen parses the code.Unlike most other documentation systems, doxygen also allows you to put the documentation of members (includingglobal functions) in front of the definition.