doxygen_manual-1.8.1 (1035109), страница 9

Просмтор этого файла доступен только зарегистрированным пользователям. Но у нас супер быстрая регистрация: достаточно только электронной почты!

Текст из файла (страница 9)

Although this is often comfortable,there may sometimes be reasons to put the documentation somewhere else. For documenting a file this is evenrequired since there is no such thing as "in front of a file".Doxygen allows you to put your documentation blocks practically anywhere (the exception is inside the body of afunction or inside a normal C style comment block).The price you pay for not putting the documentation block directly before (or after) an item is the need to put astructural command inside the documentation block, which leads to some duplication of information. So in practiceyou should avoid the use of structural commands unless other requirements force you to do so.Generated by Doxygen3.1 Special comment blocks25Structural commands (like all other commands) start with a backslash (\), or an at-sign (@) if you prefer JavaDocstyle, followed by a command name and one or more parameters. For instance, if you want to document the classTest in the example above, you could have also put the following documentation block somewhere in the input thatis read by doxygen:/*! \class Test\brief A test class.A more detailed class description.*/Here the special command \class is used to indicate that the comment block contains documentation for theclass Test.

Other structural commands are:• \struct to document a C-struct.• \union to document a union.• \enum to document an enumeration type.• \fn to document a function.• \var to document a variable or typedef or enum value.• \def to document a #define.• \typedef to document a type definition.• \file to document a file.• \namespace to document a namespace.• \package to document a Java package.• \interface to document an IDL interface.See section Special Commands for detailed information about these and many other commands.To document a member of a C++ class, you must also document the class itself. The same holds for namespaces.To document a global C function, typedef, enum or preprocessor definition you must first document the file thatcontains it (usually this will be a header file, because that file contains the information that is exported to othersource files).Let’s repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros,etc), you must document the file in which they are defined.

In other words, there must at least be a/*! \file */or a/** @file */line in this file.Here is an example of a C header named structcmd.h that is documented using structural commands:\textcolor{comment}{/*! \(\backslash\)file structcmd.h}\textcolor{comment}{\(\backslash\)brief A Documented file.}\textcolor{comment}{}\textcolor{comment}{Details.}\textcolor{comment}{*/}\textcolor{comment}{}\textcolor{comment}{/*! \(\backslash\)def MAX(a,b)}\textcolor{comment}{\(\backslash\)brief A macro that returns the maximum of \(\backslash\)a a and \(\backs\textcolor{comment}{}\textcolor{comment}{Details.}\textcolor{comment}{*/}\textcolor{comment}{}Generated by Doxygen26Documenting the code\textcolor{comment}{/*!\textcolor{comment}{\textcolor{comment}{\textcolor{comment}{\textcolor{comment}{*/}\textcolor{comment}{}\textcolor{comment}{/*!\textcolor{comment}{\textcolor{comment}{}\textcolor{comment}{\textcolor{comment}{*/}\textcolor{comment}{}\textcolor{comment}{/*!\textcolor{comment}{\textcolor{comment}{}\textcolor{comment}{\textcolor{comment}{\textcolor{comment}{*/}\textcolor{comment}{}\textcolor{comment}{/*!\textcolor{comment}{\textcolor{comment}{\textcolor{comment}{*/}\textcolor{comment}{}\textcolor{comment}{/*!\textcolor{comment}{\textcolor{comment}{\textcolor{comment}{\textcolor{comment}{\textcolor{comment}{*/}\textcolor{comment}{}\textcolor{comment}{/*!\textcolor{comment}{\textcolor{comment}{\textcolor{comment}{\textcolor{comment}{\textcolor{comment}{*/}\(\backslash\)var typedef unsigned int UINT32}\(\backslash\)brief A type definition for a .}}Details.}\(\backslash\)var int errno}\(\backslash\)brief Contains the last error code.}\(\backslash\)warning Not thread safe!}\(\backslash\)fn int open(const char *pathname,int flags)}\(\backslash\)brief Opens a file descriptor.}\(\backslash\)param pathname The name of the descriptor.}\(\backslash\)param flags Opening flags.}\(\backslash\)fn int close(int fd)}\(\backslash\)brief Closes the file descriptor \(\backslash\)a fd.}\(\backslash\)param fd The descriptor to close.}\(\backslash\)fn size\_t write(int fd,const char *buf, size\_t count)}\(\backslash\)brief Writes \(\backslash\)a count bytes from \(\backslash\)a buf to the\(\backslash\)param fd The descriptor to write to.}\(\backslash\)param buf The data buffer to write.}\(\backslash\)param count The number of bytes to write.}\(\backslash\)fn int read(int fd,char *buf,size\_t count)}\(\backslash\)brief Read bytes from a file descriptor.}\(\backslash\)param fd The descriptor to read from.}\(\backslash\)param buf The buffer to read into.}\(\backslash\)param count The number of bytes to read.}\textcolor{preprocessor}{#define MAX(a,b) (((a)>(b))?(a):(b))}\textcolor{preprocessor}{}\textcolor{keyword}{typedef} \textcolor{keywordtype}{unsigned} \textcolor{keywordtyp\textcolor{keywordtype}{int} errno;\textcolor{keywordtype}{int} open(\textcolor{keyword}{const} \textcolor{keywordtype}{char} *,\textcolor{keywor\textcolor{keywordtype}{int} close(\textcolor{keywordtype}{int});\textcolor{keywordtype}{size\_t} write(\textcolor{keywordtype}{int},\textcolor{keyword}{const} \textcolor{keyw\textcolor{keywordtype}{int} read(\textcolor{keywordtype}{int},\textcolor{keywordtype}{char} *,\textcolor{keywBecause each comment block in the example above contains a structural command, all the comment blocks could bemoved to another location or input file (the source file for instance), without affecting the generated documentation.The disadvantage of this approach is that prototypes are duplicated, so all changes have to be made twice! Becauseof this you should first consider if this is really needed, and avoid structural commands if possible.

I often receiveexamples that contain \fn command in comment blocks which are place in front of a function. This is clearly a casewhere the \fn command is redundant and will only lead to problems.3.1.2Comment blocks in PythonFor Python there is a standard way of documenting the code using so called documentation strings.

Such stringsare stored in doc and can be retrieved at runtime. Doxygen will extract such comments and assume they have tobe represented in a preformatted way.\textcolor{stringliteral}{"""@package docstring}\textcolor{stringliteral}{Documentation for this module.}\textcolor{stringliteral}{}\textcolor{stringliteral}{More details.}\textcolor{stringliteral}{"""}\textcolor{keyword}{def }func():\textcolor{stringliteral}{"""Documentation for a function.}\textcolor{stringliteral}{}Generated by Doxygen3.1 Special comment blocks27\textcolor{stringliteral}{More details.}\textcolor{stringliteral}{"""}\textcolor{keywordflow}{pass}\textcolor{keyword}{class }PyClass:\textcolor{stringliteral}{"""Documentation for a class.}\textcolor{stringliteral}{}\textcolor{stringliteral}{More details.}\textcolor{stringliteral}{"""}\textcolor{keyword}{def }\_\_init\_\_(self):\textcolor{stringliteral}{"""The constructor."""}self.\_memVar = 0;\textcolor{keyword}{def }PyMethod(self):\textcolor{stringliteral}{"""Documentation for a method."""}\textcolor{keywordflow}{pass}Note that in this case none of doxygen’s special commands are supported.There is also another way to document Python code using comments that start with "##".

These type of commentblocks are more in line with the way documentation blocks work for the other languages supported by doxygen andthis also allows the use of special commands.Here is the same example again but now using doxygen style comments:\textcolor{comment}{## @package pyexample}\textcolor{comment}{# Documentation for this module.}\textcolor{comment}{#}\textcolor{comment}{# More details.}\textcolor{comment}{## Documentation for a function.}\textcolor{comment}{#}\textcolor{comment}{# More details.}\textcolor{keyword}{def }func():\textcolor{keywordflow}{pass}\textcolor{comment}{## Documentation for a class.}\textcolor{comment}{#}\textcolor{comment}{# More details.}\textcolor{keyword}{class }PyClass:\textcolor{comment}{## The constructor.}\textcolor{keyword}{def }\_\_init\_\_(self):self.\_memVar = 0;\textcolor{comment}{## Documentation for a method.}\textcolor{comment}{# @param self The object pointer.}\textcolor{keyword}{def }PyMethod(self):\textcolor{keywordflow}{pass}\textcolor{comment}{## A class variable.}classVar = 0;\textcolor{comment}{## @var \_memVar}\textcolor{comment}{# a member variable}Since python looks more like Java than like C or C++, you should set OPTIMIZE_OUTPUT_JAVA to YES in theconfig file.3.1.3Comment blocks in VHDLFor VHDL a comment normally start with "--".

Характеристики

Список файлов лабораторной работы