doxygen_manual-1.8.1 (1035109), страница 12
Текст из файла (страница 12)
Here is anexample:This is a paragraph introducing:~~~~~~~~~~~~~~~~~~~~~a one-line code block~~~~~~~~~~~~~~~~~~~~~Generated by Doxygen38MarkdownBy default the output is the same as for a normal code block.For languages supported by doxygen you can also make the code block appear with syntax highlighting. To doso you need to indicate the typical file extension that corresponds to the programming language after the openingfence. For highlighting according to the Python language for instance, you would need to write the following:~~~~~~~~~~~~~{.py}# A classclass Dummy:pass~~~~~~~~~~~~~which will produce:\textcolor{comment}{# A class}\textcolor{keyword}{class }Dummy:\textcolor{keywordflow}{pass}and for C you would write:~~~~~~~~~~~~~~~{.c}int func(int a,int b) { return a*b; }~~~~~~~~~~~~~~~which will produce:\textcolor{keywordtype}{int} func(\textcolor{keywordtype}{int} a,\textcolor{keywordtype}{int} b) \{ \textcolorThe curly braces and dot are optional by the way.4.2.4Header Id AttributesStandard Markdown has no support for labeling headers, which is a problem if you want to link to a section.PHP Markdown Extra allows you to label a header by adding the following to the headerHeader 1========{#labelid}## Header 2 ##{#labelid2}To link to a section in the same comment block you can use[Link text](#labelid)to link to a section in general, doxygen allows you to use @ref[Link text](@ref labelid)Note this only works for the headers of level 1 to 4.4.3Doxygen specificsEven though doxygen tries to following the Markdown standard as closely as possible, there are couple of deviationand doxygen specifics additions.4.3.1Including Markdown files as pagesDoxygen can process files with Markdown formatting.
For this to work the extension for such a file should be .mdor .markdown (see EXTENSION_MAPPING if your Markdown files have a different extension, and use md as thename of the parser). Each file is converted to a page (see the page command for details).Generated by Doxygen4.3 Doxygen specifics39By default the name and title of the page are derived from the file name. If the file starts with a level 1 headerhowever, it is used as the title of the page. If you specify a label for the header (as shown here) doxygen will usethat as the page name.If the label is called index or mainpage doxygen will put the documentation on the front page (index.html).Here is an example of a file README.md that will appear as the main page when processed by doxygen:My Main Page============{#mainpage}Documentation that will appear on the main page4.3.2Treatment of HTML blocksMarkdown is quite strict in the way it processes block-level HTML:block-level HTML elements — e.g.
<div>, <table>, <pre>, <p>, etc. — must be separatedfrom surrounding content by blank lines, and the start and end tags of the block should not be indentedwith tabs or spaces.Doxygen does not have this requirement, and will also process Markdown formatting inside such HTML blocks. Theonly exception is <pre> blocks, which are passed untouched (handy for ASCII art).Doxygen will not process Markdown formatting inside verbatim or code blocks, and in other sections that need tobe processed without changes (for instance formulas or inline dot graphs).4.3.3Code Block IndentationWith Markdown any block that is indented by 4 spaces (and 8 spaces inside lists) is treated as a code block. Thisindentation amount is absolute, i.e.
counting from the start of the line.Since doxygen comments can appear at any indentation level that is required by the programming language, it usesa relative indentation instead. The amount of indentation is counted relative to the preceding paragraph. In casethere is no preceding paragraph (i.e. you want to start with a code block), the minimal amount of indentation of thewhole comment block is used as a reference.In most cases this difference does not result in different output.
Only if you play with the indentation of paragraphsthe difference is noticeable:texttexttextcodeIn this case Markdown will put the word code in a code block, whereas Doxygen will treat it as normal text, sincealthough the absolute indentation is 4, the indentation with respect to the previous paragraph is only 1.Note that list markers are not counted when determining the relative indent:1.Item1More text for item12.Item2Code block for item2For Item1 the indentation is 4 (when treating the list marker as whitespace), so the next paragraph "More text..."starts at the same indentation level and is therefore not seen as a code block.Generated by Doxygen40Markdown4.3.4Emphasis limitsUnlike standard Markdown, doxygen will not touch internal underscores or stars, so the following will appear as-is:a_nice_identifierFuthermore, a ∗ or _ only starts an emphasis if• it is followed by an alphanumberical character, and• it is preceded by a space, newline, or one the following characters <{([,:;An emphasis ends if• it is not followed by an alphanumerical character, and• it is not preceded by a space, newline, or one the following characters ({[<=+-\@Lastly, the span of the emphasis is limited to a single paragraph.4.3.5Code Spans LimitsNote that unlike standard Markdown, doxygen leaves the following untouched.A ‘cool’ word in a ‘nice’ sentence.In other words; a single quote cancels the special treatment of a code span wrapped in a pair of backtick characters.This extra restriction was added for backward compatibility reasons.4.3.6Lists ExtensionsWith Markdown two lists separated by an empty line are joined together into a single list which can be ratherunexpected and many people consider it to be a bug.
Doxygen, however, will make two separate lists as you wouldexpect.Example:- Item1 of list 1- Item2 of list 11. Item1 of list 22. Item2 of list 2Historically doxygen has an additional way to create numbered lists by using -# markers:-# item1-# item24.3.7Use of asterisksSpecial care has to be taken when using ∗’s in a comment block to start a list or make a ruler.Doxygen will strip off any leading ∗’s from the comment before doing Markdown processing. So although thefollowing works fine/** A list:* * item1* * item2*/When you remove the leading ∗’s doxygen will strip the other stars as well, making the list disappear!Rulers created with ∗’s will not be visible at all.
They only work in Markdown files.Generated by Doxygen4.4 Debugging of problems4.3.841Limits on markup scopeTo avoid that a stray ∗ or _ matches something many paragraphs later, and shows everything in between withemphasis, doxygen limits the scope of a ∗ and _ to a single paragraph.For a code span, between the starting and ending backtick only two new lines are allowed.Also for links there are limits; the link text, and link title each can contain only one new line, the URL may not containany newlines.4.4Debugging of problemsWhen doxygen parses the source code it first extracts the comments blocks, then passes these through the Markdown preprocessor.
The output of the Markdown preprocessing consists of text with special commands and HTMLcommands. A second pass takes the output of the Markdown preprocessor and converts it into the various outputformats.During Markdown preprocessing no errors are produced. Anything that does not fit the Markdown syntax is simplypassed on as-is.
In the subsequent parsing phase this could lead to errors, which may not always be obvious asthey are based on the intermediate format.To see the result after Markdown processing you can run doxygen with the -d Markdown option. It will then printeach comment block before and after Markdown processing.Generated by Doxygen42MarkdownGenerated by DoxygenChapter 5GroupingDoxygen has three mechanisms to group things together. One mechanism works at a global level, creating a newpage for each group.
These groups are called ’modules’ in the documentation. The second mechanism workswithin a member list of some compound entity, and is referred to as a ’member groups’. For pages there is a thirdgrouping mechanism referred to as subpaging.5.1ModulesModules are a way to group things together on a separate page. You can document a group as a whole, as wellas all individual members. Members of a group can be files, namespaces, classes, functions, variables, enums,typedefs, and defines, but also other groups.To define a group, you should put the \defgroup command in a special comment block. The first argument of thecommand is a label that should uniquely identify the group. The second argument is the name or title of the groupas it should appear in the documentation.You can make an entity a member of a specific group by putting a \ingroup command inside its documentation block.To avoid putting \ingroup commands in the documentation for each member you can also group members togetherby the open marker @{ before the group and the closing marker @} after the group.
The markers can be put in thedocumentation of the group definition or in a separate documentation block.Groups themselves can also be nested using these grouping markers.You will get an error message when you use the same group label more than once. If you don’t want doxygen toenforce unique labels, then you can use \addtogroup instead of \defgroup. It can be used exactly like \defgroup, butwhen the group has been defined already, then it silently merges the existing documentation with the new one.
![](https://s.studizba.com/z.php?f=/templates/si/i/noavatar.png&w=100&h=100&t=1"){kind=avatar}
