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

Doxygen will extract comments starting with "--!". There are onlytwo types of comment blocks in VHDL; a one line –! comment representing a brief description, and a multi-line –!comment (where the –! prefix is repeated for each line) representing a detailed description.Comments are always located in front of the item that is being documented with one exception: for ports thecomment can also be after the item and is then treated as a brief description for the port.Generated by Doxygen28Documenting the codeHere is an example VHDL file with doxygen comments:\textcolor{keyword}{-------------------------------------------------------}\textcolor{keyword}{}\textcolor{keyword}{--! @file}\textcolor{keyword}{}\textcolor{keyword}{--! @brief }\textcolor{vhdllogic}{2}:\textcolor{vhdllogic}{1} Mux using with-select\textco\textcolor{keyword}{-------------------------------------------------------}\textcolor{keyword}{}\textcolor{keyword}{--! Use standard library}\textcolor{vhdlkeyword}{library }\textcolor{keywordflow}{ieee};\textcolor{keyword}{}\textcolor{keyword}{--! Use logic elements}\textcolor{vhdlkeyword}{use }ieee.std\_logic\_1164.all;\textcolor{keyword}{}\textcolor{keyword}{--! Mux entity brief description}\textcolor{keyword}{}\textcolor{keyword}{--! Detailed description of this }\textcolor{keyword}{}\textcolor{keyword}{--! mux design element.}\textcolor{keywordflow}{entity }mux\_using\_with \textcolor{vhdlchar}{is}\textcolor{vhdlchar}{port} \textcolor{vhdlchar}{(}\textcolor{vhdlchar}{din\_0}\textcolor{vhdlchar}{:} \textcolor{vhdlchar}{in} \textcolor{vhdlchar}{\textcolor{vhdlchar}{din\_1}\textcolor{vhdlchar}{:} \textcolor{vhdlchar}{in} \textcolor{vhdlchar}{\textcolor{vhdlchar}{sel}\textcolor{vhdlchar}{:} \textcolor{vhdlchar}{in} \textcolor{vhdlchar}{s\textcolor{vhdlchar}{mux\_out} \textcolor{vhdlchar}{:} \textcolor{vhdlchar}{out} \textcolor{vhdlchar}{\textcolor{vhdlchar}{)};\textcolor{vhdlchar}{end} \textcolor{vhdlchar}{entity};\textcolor{keyword}{}\textcolor{keyword}{--! @brief Architure definition of the MUX}\textcolor{keyword}{}\textcolor{keyword}{--! @details More details about this mux element.}architecture behavior of mux\_using\_with is\textcolor{vhdlkeyword}{begin}\textcolor{vhdlchar}{with} \textcolor{vhdlchar}{(}\textcolor{vhdlchar}{sel}\textcolor{vhdlchar}{)} \textco\textcolor{vhdlchar}{mux\_out} \textcolor{vhdlchar}{<=} \textcolor{vhdlchar}{din\_0} \textcolor{vhdlchar}{\textcolor{vhdlchar}{din\_1} \textcolor{vhdlchar}{when} \textcolor{vhdlchar}{others};\textcolor{vhdlchar}{end} \textcolor{vhdlchar}{architecture};To get proper looking output you need to set OPTIMIZE_OUTPUT_VHDL to YES in the config file.

This will alsoaffect a number of other settings. When they were not already set correctly doxygen will produce a warning tellingwhich settings where overruled.3.1.4Comment blocks in FortranWhen using doxygen for Fortran code you should set OPTIMIZE_FOR_FORTRAN to YES.For Fortran "!>" or "!<" starts a comment and "!!" or "!>" can be used to continuate a one line comment into amulti-line comment.Here is an example of a documented Fortran subroutine:!> Build the restriction matrix for the aggregation!! method.!! @param aggr information about the aggregates!! @todo Handle special casesubroutine IntRestBuild(A,aggr,Restrict,A_ghost)implicit noneType(SpMtx), intent(in) :: A !< our fine level matrixType(Aggrs), intent(in) :: aggrType(SpMtx), intent(out) :: Restrict !< Our restriction matrixAs a alternative you can also use comments in fixed format code:C> Function commentC> another line of commentfunction A(i)C> input parameterinteger iend function AGenerated by Doxygen3.1 Special comment blocks3.1.529Comment blocks in TclDoxygen documentation can be included in normal Tcl comments.To start a new documentation block start a line with ## (two hashes).

All following comment lines and continuationlines will be added to this block. The block ends with a line not starting with a # (hash sign).A brief documentation can be added with ;#< (semicolon, hash and lower then sign). The brief documentation alsoends at a line not starting with a # (hash sign).Inside doxygen comment blocks all normal doxygen markings are supported. The only exceptions are described inthe following two paragraphs.If a doxygen comment block ends with a line containing only #\code or #@code all code until a line only containing#\endcode or #@endcode is added to the generated documentation as code block.If a doxygen comment block ends with a line containing only #\verbatim or #@verbatim all code until a lineonly containing #\endverbatim or #@endverbatim is added verbatim to the generated documentation.To detect namespaces, classes, functions and variables the following Tcl commands are recognized.

Documentation blocks can be put on the lines before the command.• namespace eval .. Namespace• proc .. Function• variable .. Variable• common .. Common variable• itcl::class .. Class• itcl::body .. Class method body definition• oo::class create .. Class• oo::define .. OO Class definition• method .. Class method definitions• constructor .. Class constructor• destructor .. Class destructor• public ..

Set protection level• protected .. Set protection level• private .. Set protection levelFollowing is a example using doxygen style comments:1 \textcolor{comment}{## \(\backslash\)file tclexample.tcl}2 \textcolor{comment}{}\textcolor{comment}{# File documentation.}3 \textcolor{comment}{}\textcolor{comment}{#\(\backslash\)verbatim}4 \textcolor{comment}{}5 \textcolor{comment}{# Startup code:\(\backslash\)}6 \textcolor{comment}{}\textcolor{comment}{exec tclsh "$0" "$@"}7 \textcolor{comment}{}\textcolor{comment}{#\(\backslash\)endverbatim}8 \textcolor{comment}{}\textcolor{comment}{## Documented namespace \(\backslash\)c ns .}9 \textcolor{comment}{}\textcolor{comment}{# The code is inserted here:}10 \textcolor{comment}{}\textcolor{comment}{#\(\backslash\)code}11 \textcolor{comment}{}\textcolor{keyword}{namespace} \textcolor{keyword}{eval} ns \{12\textcolor{comment}{## Documented proc \(\backslash\)c ns\_proc .}13 \textcolor{comment}{}\textcolor{comment}{ }\textcolor{comment}{# param[in] arg some argument}14 \textcolor{comment}{}\textcolor{comment}{ }\textcolor{keyword}{proc} ns\_proc \{arg\} \{\}\textcolor{comm}15 \textcolor{comment}{} \textcolor{comment}{## Documented var \(\backslash\)c ns\_var .}16 \textcolor{comment}{}\textcolor{comment}{ }\textcolor{comment}{# Some documentation.}17 \textcolor{comment}{}\textcolor{comment}{ }\textcolor{keyword}{variable} ns\_var\textcolor{comment}{Generated by Doxygen30Documenting the code}18 \textcolor{comment}{} \textcolor{comment}{## Documented itcl class \(\backslash\)c itcl\_class .}19 \textcolor{comment}{}\textcolor{comment}{ }\textcolor{keyword}{itcl::class} itcl\_class \{20\textcolor{comment}{## Create object.}21 \textcolor{comment}{}\textcolor{comment}{}\textcolor{keyword}{constructor} \{args\} \{\textcolor{keywo}22 \textcolor{comment}{}\textcolor{comment}{## Destroy object.}23 \textcolor{comment}{}\textcolor{comment}{}\textcolor{keyword}{destructor} \{\textcolor{keyword}{exit}\}24 \textcolor{comment}{}\textcolor{comment}{## Documented itcl method \(\backslash\)c itcl\_method\_x .}25 \textcolor{comment}{}\textcolor{comment}{}\textcolor{comment}{# param[in] arg Argument}26 \textcolor{comment}{}\textcolor{comment}{}\textcolor{keyword}{private} \textcolor{keyword}{method} itc}27 \textcolor{comment}{}\textcolor{comment}{## Documented itcl method \(\backslash\)c itcl\_method\_y .}28 \textcolor{comment}{}\textcolor{comment}{}\textcolor{comment}{# param[in] arg Argument}29 \textcolor{comment}{}\textcolor{comment}{}\textcolor{keyword}{protected} \textcolor{keyword}{method} i}30 \textcolor{comment}{}\textcolor{comment}{## Documented itcl method \(\backslash\)c itcl\_method\_z .}31 \textcolor{comment}{}\textcolor{comment}{}\textcolor{comment}{# param[in] arg Argument}32 \textcolor{comment}{}\textcolor{comment}{}\textcolor{keyword}{public} \textcolor{keyword}{method} itcl}33 \textcolor{comment}{}\textcolor{comment}{## Documented common itcl var \(\backslash\)c itcl\_Var .}34 \textcolor{comment}{}\textcolor{comment}{}\textcolor{keyword}{common} itcl\_Var\textcolor{comment}{}35 \textcolor{comment}{}\textcolor{comment}{## \(\backslash\)protectedsection}36 \textcolor{comment}{}\textcolor{comment}{}37\textcolor{keyword}{variable} itcl\_var1\textcolor{comment}{;#< Documented itcl var \(\backslash\)c itc}38 \textcolor{comment}{}\textcolor{keyword}{variable} itcl\_var2\}\textcolor{comment}{}39 \textcolor{comment}{} \textcolor{comment}{## Documented oo class \(\backslash\)c oo\_class .}40 \textcolor{comment}{}\textcolor{comment}{ }\textcolor{keyword}{oo::class} create oo\_class \{41\textcolor{comment}{## Create object.}42 \textcolor{comment}{}\textcolor{comment}{}\textcolor{comment}{# Configure with args}43 \textcolor{comment}{}\textcolor{comment}{}\textcolor{keyword}{constructor} \{args\} \{\textcolor{keywo}44 \textcolor{comment}{}\textcolor{comment}{## Destroy object.}45 \textcolor{comment}{}\textcolor{comment}{}\textcolor{comment}{# Exit.}46 \textcolor{comment}{}\textcolor{comment}{}\textcolor{keyword}{destructor} \{\textcolor{keyword}{exit}\}47 \textcolor{comment}{}\textcolor{comment}{## Documented oo var \(\backslash\)c oo\_var .}48 \textcolor{comment}{}\textcolor{comment}{}\textcolor{comment}{# Defined inside class}49 \textcolor{comment}{}\textcolor{comment}{}\textcolor{keyword}{variable} oo\_var\textcolor{comment}{}50 \textcolor{comment}{}\textcolor{comment}{## \(\backslash\)private Documented oo method \(\backslash\)c}51 \textcolor{comment}{}\textcolor{comment}{}\textcolor{comment}{# param[in] arg Argument}52 \textcolor{comment}{}\textcolor{comment}{}\textcolor{keyword}{method} oo\_method\_x \{arg\} \{\}\textc}53 \textcolor{comment}{}\textcolor{comment}{## \(\backslash\)protected Documented oo method \(\backslash\}54 \textcolor{comment}{}\textcolor{comment}{}\textcolor{comment}{# param[in] arg Argument}55 \textcolor{comment}{}\textcolor{comment}{}\textcolor{keyword}{method} oo\_method\_y \{arg\} \{\}\textc}56 \textcolor{comment}{}\textcolor{comment}{## \(\backslash\)public Documented oo method \(\backslash\)c}57 \textcolor{comment}{}\textcolor{comment}{}\textcolor{comment}{# param[in] arg Argument}58 \textcolor{comment}{}\textcolor{comment}{}\textcolor{keyword}{method} oo\_method\_z \{arg\} \{\}\textc}59 \textcolor{comment}{} \}\textcolor{comment}{}60 \textcolor{comment}{}\}\textcolor{comment}{}61 \textcolor{comment}{}\textcolor{comment}{#\(\backslash\)endcode}62 \textcolor{comment}{}63 \textcolor{keyword}{itcl::body} ::ns::itcl\_class::itcl\_method\_x \{argx\} \{64\textcolor{keyword}{puts} "$argx OK"\textcolor{comment}{}65 \textcolor{comment}{}\}\textcolor{comment}{}66 \textcolor{comment}{}67 \textcolor{keyword}{oo::define} ns::oo\_class \{68\textcolor{comment}{## \(\backslash\)public Outside defined variable \(\backslash\)c oo\_var\_out .}69 \textcolor{comment}{}\textcolor{comment}{ }\textcolor{comment}{# Inside oo\_class}70 \textcolor{comment}{}\textcolor{comment}{ }\textcolor{keyword}{variable} oo\_var\_out\textcolor{comment}{}71 \textcolor{comment}{}\}\textcolor{comment}{}72 \textcolor{comment}{}73 \textcolor{comment}{## Documented global proc \(\backslash\)c glob\_proc .}74 \textcolor{comment}{}\textcolor{comment}{# param[in] arg Argument}75 \textcolor{comment}{}\textcolor{keyword}{proc} glob\_proc \{arg\} \{\textcolor{keyword}{puts} $arg\}\textc}76 \textcolor{comment}{}77 \textcolor{keyword}{variable} glob\_var\textcolor{comment}{;#< Documented global var \(\backslash\)c glob\_}78 \textcolor{comment}{ with newline}79 \textcolor{comment}{#< and continued line}80 \textcolor{comment}{}81 \textcolor{comment}{# end of file}3.2Anatomy of a comment blockThe previous section focused on how to make the comments in your code known to doxygen, it explained thedifference between a brief and a detailed description, and the use of structural commands.Generated by Doxygen3.2 Anatomy of a comment block31In this section we look at the contents of the comment block itself.Doxygen supports various styles of formatting your comments.The simplest form is to use plain text.