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

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

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

This disables the generation of the built-in class inheritance diagrams.• An include dependency graph is generated for each documented file that includes at least one other file. Thisfeature is currently supported for HTML and RTF only.• An inverse include dependency graph is also generated showing for a (header) file, which other files includeit.• A graph is drawn for each documented class and struct that shows:– the inheritance relations with base classes.– the usage relations with other structs and classes (e.g. class A has a member variable m_a of typeclass B, then A has an arrow to B with m_a as label).• if CALL_GRAPH is set to YES, a graphical call graph is drawn for each function showing the functions thatthe function directly or indirectly calls.• if CALLER_GRAPH is set to YES, a graphical caller graph is drawn for each function showing the functionsthat the function is directly or indirectly called by.Using a layout file you can determine which of the graphs are actually shown.The options DOT_GRAPH_MAX_NODES and MAX_DOT_GRAPH_DEPTH can be used to limit the size of thevarious graphs.The elements in the class diagrams in HTML and RTF have the following meaning:• A yellow box indicates a class.

A box can have a little marker in the lower right corner to indicate that theclass contains base classes that are hidden. For the class diagrams the maximum tree width is currently 8elements. If a tree is wider some nodes will be hidden. If the box is filled with a dashed pattern the inheritancerelation is virtual.52Graphs and diagrams• A white box indicates that the documentation of the class is currently shown.• A gray box indicates an undocumented class.• A solid dark blue arrow indicates public inheritance.• A dashed dark green arrow indicates protected inheritance.• A dotted dark green arrow indicates private inheritance.The elements in the class diagram in LATEX have the following meaning:• A white box indicates a class.

A marker in the lower right corner of the box indicates that the class has baseclasses that are hidden. If the box has a dashed border this indicates virtual inheritance.• A solid arrow indicates public inheritance.• A dashed arrow indicates protected inheritance.• A dotted arrow indicates private inheritance.The elements in the graphs generated by the dot tool have the following meaning:• A white box indicates a class or struct or file.• A box with a red border indicates a node that has more arrows than are shown! In other words: the graphis truncated with respect to this node.

The reason why a graph is sometimes truncated is to prevent imagesfrom becoming too large. For the graphs generated with dot doxygen tries to limit the width of the resultingimage to 1024 pixels.• A black box indicates that the class’ documentation is currently shown.• A dark blue arrow indicates an include relation (for the include dependency graph) or public inheritance (forthe other graphs).• A dark green arrow indicates protected inheritance.• A dark red arrow indicates private inheritance.• A purple dashed arrow indicated a "usage" relation, the edge of the arrow is labeled with the variable(s)responsible for the relation.

Class A uses class B, if class A has a member variable m of type C, where B is asubtype of C (e.g. C could be B, B∗, T\<B\>∗).Here are a couple of header files that together show the various diagrams that doxygen can generate:diagrams_a.h#ifndef _DIAGRAMS_A_H#define _DIAGRAMS_A_Hclass A { public: A *m_self; };#endifdiagrams_b.h#ifndef _DIAGRAMS_B_H#define _DIAGRAMS_B_Hclass A;class B { public: A *m_a; };#endifdiagrams_c.h#ifndef _DIAGRAMS_C_H#define _DIAGRAMS_C_H#include "diagrams_c.h"class D;class C : public A { public: D *m_d; };#endifGenerated by Doxygen53diagrams_d.h#ifndef _DIAGRAM_D_H#define _DIAGRAM_D_H#include "diagrams_a.h"#include "diagrams_b.h"class C;class D : virtual protected#endifdiagrams_e.h#ifndef _DIAGRAM_E_H#define _DIAGRAM_E_H#include "diagrams_d.h"class E : public D {};#endifGenerated by DoxygenA, private B { public: C m_c; };54Graphs and diagramsGenerated by DoxygenChapter 8PreprocessingSource files that are used as input to doxygen can be parsed by doxygen’s built-in C-preprocessor.By default doxygen does only partial preprocessing.

That is, it evaluates conditional compilation statements (like#if) and evaluates macro definitions, but it does not perform macro expansion.So if you have the following code fragment#define VERSION 200#define CONST_STRING const char *#if VERSION >= 200static CONST_STRING version = "2.xx";#elsestatic CONST_STRING version = "1.xx";#endifThen by default doxygen will feed the following to its parser:#define VERSION#define CONST_STRINGstatic CONST_STRING version = "2.xx";You can disable all preprocessing by setting ENABLE_PREPROCESSING to NO in the configuration file. In thecase above doxygen will then read both statements, i.e.:static CONST_STRING version = "2.xx";static CONST_STRING version = "1.xx";In case you want to expand the CONST_STRING macro, you should set the MACRO_EXPANSION tag in theconfig file to YES.

Then the result after preprocessing becomes:#define VERSION#define CONST_STRINGstatic const char * version = "1.xx";Note that doxygen will now expand all macro definitions (recursively if needed). This is often too much. Therefore,doxygen also allows you to expand only those defines that you explicitly specify. For this you have to set theEXPAND_ONLY_PREDEF tag to YES and specify the macro definitions after the PREDEFINED or EXPAND_AS_DEFINED tag.A typically example where some help from the preprocessor is needed is when dealing with Microsoft’s declspeclanguage extension. The same goes for GNU’s __attribute extension.

Here is an example function.extern "C" void __declspec(dllexport) ErrorMsg( String aMessage,...);56PreprocessingWhen nothing is done, doxygen will be confused and see __declspec as some sort of function. To help doxygenone typically uses the following preprocessor settings:ENABLE_PREPROCESSINGMACRO_EXPANSIONEXPAND_ONLY_PREDEFPREDEFINED====YESYESYES__declspec(x)=This will make sure the __declspec(dllexport) is removed before doxygen parses the source code.For a more complex example, suppose you have the following obfuscated code fragment of an abstract base classcalled IUnknown:/*! A reference to an IID */#ifdef __cplusplus#define REFIID const IID &#else#define REFIID const IID *#endif/*! The IUnknown interface */DECLARE_INTERFACE(IUnknown){STDMETHOD(HRESULT,QueryInterface) (THIS_ REFIID iid, void **ppv) PURE;STDMETHOD(ULONG,AddRef) (THIS) PURE;STDMETHOD(ULONG,Release) (THIS) PURE;};without macro expansion doxygen will get confused, but we may not want to expand the REFIID macro, because itis documented and the user that reads the documentation should use it when implementing the interface.By setting the following in the config file:ENABLE_PREPROCESSINGMACRO_EXPANSIONEXPAND_ONLY_PREDEFPREDEFINED====YESYESYES"DECLARE_INTERFACE(name)=class name" \"STDMETHOD(result,name)=virtual result name" \"PURE= = 0" \THIS_= \THIS= \__cpluspluswe can make sure that the proper result is fed to doxygen’s parser:/*! A reference to an IID */#define REFIID/*! The IUnknown interface */class IUnknown{virtual HRESULTQueryInterface ( REFIID iid, void **ppv) = 0;virtual ULONGAddRef () = 0;virtual ULONGRelease () = 0;};Note that the PREDEFINED tag accepts function like macro definitions (like DECLARE_INTERFACE ), normalmacro substitutions (like PURE and THIS) and plain defines (like __cplusplus).Note also that preprocessor definitions that are normally defined automatically by the preprocessor (like __cplusplus), have to be defined by hand with doxygen’s parser (this is done because these defines are oftenplatform/compiler specific).In some cases you may want to substitute a macro name or function by something else without exposing the resultto further macro substitution.

You can do this but using the := operator instead of =As an example suppose we have the following piece of code:Generated by Doxygen57#define QList QListTclass QListT{};Then the only way to get doxygen interpret this as a class definition for class QList is to define:PREDEFINED = QListT:=QListHere is an example provided by Valter Minute and Reyes Ponce that helps doxygen to wade through the boilerplatecode in Microsoft’s ATL & MFC libraries:PREDEFINED= "DECLARE_INTERFACE(name)=class name" \"STDMETHOD(result,name)=virtual result name" \"PURE= = 0" \THIS_= \THIS= \DECLARE_REGISTRY_RESOURCEID=// \DECLARE_PROTECT_FINAL_CONSTRUCT=// \"DECLARE_AGGREGATABLE(Class)= " \"DECLARE_REGISTRY_RESOURCEID(Id)= " \DECLARE_MESSAGE_MAP= \BEGIN_MESSAGE_MAP=/* \END_MESSAGE_MAP=*/// \BEGIN_COM_MAP=/* \END_COM_MAP=*/// \BEGIN_PROP_MAP=/* \END_PROP_MAP=*/// \BEGIN_MSG_MAP=/* \END_MSG_MAP=*/// \BEGIN_PROPERTY_MAP=/* \END_PROPERTY_MAP=*/// \BEGIN_OBJECT_MAP=/* \END_OBJECT_MAP()=*/// \DECLARE_VIEW_STATUS=// \"STDMETHOD(a)=HRESULT a" \"ATL_NO_VTABLE= " \"__declspec(a)= " \BEGIN_CONNECTION_POINT_MAP=/* \END_CONNECTION_POINT_MAP=*/// \"DECLARE_DYNAMIC(class)= " \"IMPLEMENT_DYNAMIC(class1, class2)= " \"DECLARE_DYNCREATE(class)= " \"IMPLEMENT_DYNCREATE(class1, class2)= " \"IMPLEMENT_SERIAL(class1, class2, class3)= " \"DECLARE_MESSAGE_MAP()= " \TRY=try \"CATCH_ALL(e)= catch(...)" \END_CATCH_ALL= \"THROW_LAST()= throw"\"RUNTIME_CLASS(class)=class" \"MAKEINTRESOURCE(nId)=nId" \"IMPLEMENT_REGISTER(v, w, x, y, z)= " \"ASSERT(x)=assert(x)" \"ASSERT_VALID(x)=assert(x)" \"TRACE0(x)=printf(x)" \"OS_ERR(A,B)={ #A, B }" \__cplusplus \"DECLARE_OLECREATE(class)= " \"BEGIN_DISPATCH_MAP(class1, class2)= " \"BEGIN_INTERFACE_MAP(class1, class2)= " \"INTERFACE_PART(class, id, name)= " \"END_INTERFACE_MAP()=" \"DISP_FUNCTION(class, name, function, result, id)=" \"END_DISPATCH_MAP()=" \"IMPLEMENT_OLECREATE2(class, name, id1, id2, id3, id4,\id5, id6, id7, id8, id9, id10, id11)="As you can see doxygen’s preprocessor is quite powerful, but if you want even more flexibility you can always writean input filter and specify it after the INPUT_FILTER tag.If you are unsure what the effect of doxygen’s preprocessing will be you can run doxygen as follows:Generated by Doxygen58Preprocessingdoxygen -d PreprocessorThis will instruct doxygen to dump the input sources to standard output after preprocessing has been done (Hint:set QUIET = YES and WARNINGS = NO in the configuration file to disable any other output).Generated by DoxygenChapter 9Automatic link generationMost documentation systems have special ‘see also’ sections where links to other pieces of documentation can beinserted.

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

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