diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/commands.doc | 79 | ||||
| -rw-r--r-- | doc/config.doc | 14 | ||||
| -rw-r--r-- | doc/faq.doc | 13 | ||||
| -rw-r--r-- | doc/infoflow.gif | bin | 12508 -> 24468 bytes | |||
| -rw-r--r-- | doc/install.doc | 116 | ||||
| -rw-r--r-- | doc/language.doc | 6 | ||||
| -rw-r--r-- | doc/preprocessing.doc | 26 | ||||
| -rw-r--r-- | doc/translator_report.txt | 22 |
8 files changed, 191 insertions, 85 deletions
diff --git a/doc/commands.doc b/doc/commands.doc index b3af6d0..26e58ca 100644 --- a/doc/commands.doc +++ b/doc/commands.doc @@ -51,6 +51,7 @@ documentation: \refitem cmdcategory \\category \refitem cmdclass \\class \refitem cmdcode \\code +\refitem cmdcond \\cond \refitem cmdcopydoc \\copydoc \refitem cmddate \\date \refitem cmddef \\def @@ -65,6 +66,7 @@ documentation: \refitem cmdelseif \\elseif \refitem cmdem \\em \refitem cmdendcode \\endcode +\refitem cmdendcond \\endcond \refitem cmdenddot \\enddot \refitem cmdendhtmlonly \\endhtmlonly \refitem cmdendif \\endif @@ -223,6 +225,7 @@ doxygen. Unrecognized commands are treated as normal text. \sa section \ref cmdclass "\\class". +<hr> \section cmdclass \class <name> [<header-file>] [<header-name>] \addindex \\class @@ -755,6 +758,72 @@ See section \ref memgroup for an example. for an example. <hr> +\section cmdcond \cond [<section-label>] + + \addindex \\cond + Starts a conditional section that ends with a corresponding + \ref cmdendcond "\\endcond" command, which is typically found in + another comment block. The main purpose of this pair of + commands is to (conditionally) exclude part of a file from processing + (traditionally this could only be achieved using C processor commands). + + The section between \\cond and \\endcond commands can be included by + adding its section label to the \ref cfg_enabled_sections "ENABLED_SECTIONS" + configuration option. If the section label is omitted, the section will + be excluded from processing unconditionally. + + For conditional sections within a comment block one should + use a \ref cmdif "\\if" ... \ref cmdendif "\\endif" block. + + Conditional sections can be nested. In this case a nested section will only + be shown if it and its containing section are included. + + Here is an example showing the commands in action: + +\verbatim +/** An interface */ +class Intf +{ + public: + /** A method */ + virtual void func() = 0; + + /// @cond TEST + + /** A method used for testing */ + virtual void test() = 0; + + /// @endcond +}; + +/// @cond DEV +/* + * The implementation of the interface + */ +class Implementation : public Intf +{ + public: + void func(); + + /// @cond TEST + void test(); + /// @endcond + + /// @cond + /** This method is obsolete and does + * not show up in the documentation. + */ + void obsolete(); + /// @endcond +}; + +/// @endcond +\endverbatim + +The output will be different depending on whether \c ENABLED_SECTIONS +is empty, \c TEST, \c DEV, or \c DEV \c TEST. + +<hr> \section cmddate \date { date description } \addindex \\date @@ -804,10 +873,18 @@ See section \ref memgroup for an example. \ref cmdelse "\\else", and \ref cmdelseif "\\elseif". <hr> +\section cmdendcond \endcond + + \addindex \\endcond + Ends a conditional section that was started by \ref cmdcond "\\cond". + + \sa \ref cmdcond "\\cond". + +<hr> \section cmdendif \endif \addindex \\endif - Ends a conditional section that was started with \c \\if or \c \\ifnot + Ends a conditional section that was started by \c \\if or \c \\ifnot For each \c \\if or \c \\ifnot one and only one matching \c \\endif must follow. \sa \ref cmdif "\\if", and \ref cmdifnot "\\ifnot". diff --git a/doc/config.doc b/doc/config.doc index af065ec..e1e9472 100644 --- a/doc/config.doc +++ b/doc/config.doc @@ -73,6 +73,7 @@ followed by the descriptions of the tags grouped by category. \refitem cfg_compact_rtf COMPACT_RTF \refitem cfg_create_subdirs CREATE_SUBDIRS \refitem cfg_details_at_top DETAILS_AT_TOP +\refitem cfg_directory_graph DIRECTORY_GRAPH \refitem cfg_disable_index DISABLE_INDEX \refitem cfg_distribute_group_doc DISTRIBUTE_GROUP_DOC \refitem cfg_dot_image_format DOT_IMAGE_FORMAT @@ -609,7 +610,8 @@ function's detailed documentation block. \addindex ENABLED_SECTIONS The \c ENABLED_SECTIONS tag can be used to enable conditional documentation sections, marked by \ref cmdif "\\if" \<section-label\> ... - \ref cmdendif "\\endif" blocks. + \ref cmdendif "\\endif" and \ref cmdcond "\\cond" \<section-label\> ... + \ref cmdendcond "\\endcond" blocks. \anchor cfg_max_initializer_lines <dt>\c MAX_INITIALIZER_LINES <dd> @@ -1583,10 +1585,18 @@ TAGFILES = file1=loc1 "file2 = loc2" ... </pre> If the \c GRAPHICAL_HIERARCHY and \c HAVE_DOT tags are set to \c YES then doxygen will graphical hierarchy of all classes instead of a textual one. +\anchor cfg_directory_graph +<dt>\c DIRECTORY_GRAPH <dd> + \addindex DIRECTORY_GRAPH + If the \c DIRECTORY_GRAPH, \c SHOW_DIRECTORIES and \c HAVE_DOT options are set + to \c YES then doxygen will show the dependencies a directory has on other directories + in a graphical way. The dependency relations are determined by the #include + relations between the files in the directories. + \anchor cfg_dot_image_format <dt>\c DOT_IMAGE_FORMAT <dd> \addindex DOT_IMAGE_FORMAT - The DOT_IMAGE_FORMAT tag can be used to set the image format of the images + The \c DOT_IMAGE_FORMAT tag can be used to set the image format of the images generated by dot. Possible values are gif, jpg, and png. If left blank png will be used. diff --git a/doc/faq.doc b/doc/faq.doc index fb8bb0b..8cd217d 100644 --- a/doc/faq.doc +++ b/doc/faq.doc @@ -79,7 +79,13 @@ document either the class or namespace. <li><b>How can I make doxygen ignore some code fragment?</b> <p> -You can use Doxygen's preprocessor for this: + +The new and easiest way is to add one comment block +with a \ref cmdcond "\\cond" command at the start and one comment block +with a \ref cmdendcond "\\endcond" command at the end of the piece of +code that should be ignored. This should be within the same file of course. + +But you can also use Doxygen's preprocessor for this: If you put \verbatim #ifndef DOXYGEN_SHOULD_SKIP_THIS @@ -97,7 +103,10 @@ as <code>PREPROCESSING = YES</code>. <li><b>How can I change what is after the <code>\#include</code> in the class documentation?</b> -You can document your class like +In most cases you can use STRIP_FROM_INC_PATH to strip a user defined +part of a path. + +You can also document your class as follows \verbatim /*! \class MyClassName include.h path/include.h diff --git a/doc/infoflow.gif b/doc/infoflow.gif Binary files differindex f26763e..7b4468b 100644 --- a/doc/infoflow.gif +++ b/doc/infoflow.gif diff --git a/doc/install.doc b/doc/install.doc index 8546efe..3c9a74b 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -385,7 +385,9 @@ Currently, I have only compiled doxygen for Windows using Microsoft's Visual C++ (version 6.0). For other compilers you may need to edit the perl script in <code>wintools/make.pl</code> a bit. Let me know what you had to change if you got Doxygen working with another -compiler. +compiler. If you have Visual Studio you can also use the .dsw file found in +the <code>wintools</code> directory. Note that this file is not maintained +by me, so it might be outdated a little. If you have Visual C++ 6.0, and the source distribution, you can easily build doxygen using the project files in the \c wintools directory. If @@ -462,57 +464,16 @@ Here is what is required: commerical version of Qt. For doxywizard, a complete Qt library is - still a requirement however. You can download the non-commercial version - from Troll-Tech web-site. See doxygen download page for a link. + still a requirement however. A commercial license to build + doxywizard with the latest Qt library was kindly donated to me + by the nice people at <a href="http://www.trolltech.com">TrollTech</a>. + See doxygen download page for a link. -<li>To generate LaTeX documentation or formulas in HTML you need the tools: - <code>latex</code>, <code>dvips</code> and <code>gswin32</code>. - To get these working under Windows - install the fpTeX distribution. You can find more info at: - http://www.fptex.org/ and download it from CTAN or one of its mirrors. - In the Netherlands for example this would be: - ftp://ftp.easynet.nl/mirror/CTAN/systems/win32/fptex/ - - Make sure the tools are available from a dos box, by adding the - directory they are in to the search path. - - For your information, the LaTeX is freely available set of so - called macros and styles on the top of the famous TeX program - (by famous Donald Knuth) and the accompanied utilities (all - available for free). It is used for high quality - typesetting. The result -- in the form of so called - <code>DVI</code> (DeVice Independent) file -- can be printed or - displayed on various devices preserving exactly the same look up - to the capability of the device. The <code>dvips</code> allows you - to convert the <code>dvi</code> to the high quality PostScript - (i.e. PostScript that can be processed by utilities like - <code>psnup</code>, <code>psbook</code>, <code>psselect</code>, - and others). The derived version of TeX (the pdfTeX) can be used - to produce PDF output instead of DVI, or the PDF can be produced - from PostScript using the utility <code>ps2pdf</code>. - - If you want to use MikTeX then you need to select at least the - medium size installation. For really old versions of MikTex or minimal - installations, you may need to download the fancyhdr package separately. - You can find it at: - ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/ - -<li>If you want to generate compressed HTML help - (see \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the - config file, then you need the Microsoft HTML help workshop. - You can download it at: - http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconHH1Start.asp - <li>If you used WinZip to extract the tar archive it will (apparently) not create empty folders, so you have to add the folders <code>objects</code> and <code>bin</code> manually in the root of the distribution before compiling. -<li><a href="http://www.research.att.com/sw/tools/graphviz/"> - the Graph visualization toolkit version 1.8.10</a><br> - \latexonly(see {\tt http://www.research.att.com/sw/tools/graphviz/})\endlatexonly. - Needed for the include dependency graphs, the graphical inheritance graphs, - and the collaboration graphs. </ul> @@ -577,23 +538,66 @@ To install doxygen, just copy the binaries from the <code>bin</code> directory to a location somewhere in the path. Alternatively, you can include the <code>bin</code> directory of the distribution to the path. -<!-- -For running doxywizard you need to install the non-commercial version of -the Qt library first. This library can be downloaded from -http://www.trolltech.com/products/download/qt-win-noncomm.html ---> +There are a couple of tools you may want to install to use all of doxygen's +features: + +<ul> +<li>To generate LaTeX documentation or formulas in HTML you need the tools: + <code>latex</code>, <code>dvips</code> and <code>gswin32</code>. + To get these working under Windows + install the fpTeX distribution. You can find more info at: + http://www.fptex.org/ and download it from CTAN or one of its mirrors. + In the Netherlands for example this would be: + ftp://ftp.easynet.nl/mirror/CTAN/systems/win32/fptex/ + + Make sure the tools are available from a dos box, by adding the + directory they are in to the search path. + + For your information, the LaTeX is freely available set of so + called macros and styles on the top of the famous TeX program + (by famous Donald Knuth) and the accompanied utilities (all + available for free). It is used for high quality + typesetting. The result -- in the form of so called + <code>DVI</code> (DeVice Independent) file -- can be printed or + displayed on various devices preserving exactly the same look up + to the capability of the device. The <code>dvips</code> allows you + to convert the <code>dvi</code> to the high quality PostScript + (i.e. PostScript that can be processed by utilities like + <code>psnup</code>, <code>psbook</code>, <code>psselect</code>, + and others). The derived version of TeX (the pdfTeX) can be used + to produce PDF output instead of DVI, or the PDF can be produced + from PostScript using the utility <code>ps2pdf</code>. + + If you want to use MikTeX then you need to select at least the + medium size installation. For really old versions of MikTex or minimal + installations, you may need to download the fancyhdr package separately. + You can find it at: + ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/ + +<li>If you want to generate compressed HTML help + (see \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the + config file, then you need the Microsoft HTML help workshop. + You can download it at: + http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconHH1Start.asp + +<li><a href="http://www.research.att.com/sw/tools/graphviz/"> + the Graph visualization toolkit version 1.8.10</a><br> + \latexonly(see {\tt http://www.research.att.com/sw/tools/graphviz/})\endlatexonly. + Needed for the include dependency graphs, the graphical inheritance graphs, + and the collaboration graphs. +</ul> \section build_tools Tools used to develop doxygen Doxygen was developed and tested under Linux using the following open-source tools: <ul> -<li>GCC version 2.95.3 +<li>GCC version 3.3.1 <li>GNU flex version 2.5.4 -<li>GNU bison version 1.35 -<li>GNU make version 3.79.1 -<li>Perl version 5.005_03 -<li>VIM version 5.8 +<li>GNU bison version 1.75 +<li>GNU make version 3.80 +<li>Perl version 5.8.1 +<li>VIM version 6.2 <li>Mozilla 1.0 <li>Troll Tech's tmake version 1.3 (included in the distribution) <li>teTeX version 1.0 diff --git a/doc/language.doc b/doc/language.doc index 7281318..ba92211 100644 --- a/doc/language.doc +++ b/doc/language.doc @@ -23,7 +23,7 @@ text fragments, generated by doxygen, can be produced in languages other than English (the default). The output language is chosen through the configuration file (with default name and known as Doxyfile). -Currently (version 1.3.9), 30 languages +Currently (version 1.3.9.1), 30 languages are supported (sorted alphabetically): Afrikaans, Brazilian Portuguese, Catalan, Chinese, Chinese Traditional, Croatian, Czech, Danish, Dutch, English, Finnish, French, @@ -210,7 +210,7 @@ when the translator was updated. <td>Serbian</td> <td>Dejan Milosavljevic</td> <td>dmilos at email dot com</td> - <td>1.3.8</td> + <td>up-to-date</td> </tr> <tr bgcolor="#ffffff"> <td>Slovak</td> @@ -318,7 +318,7 @@ when the translator was updated. \hline Russian & Alexandr Chelpanov & {\tt\tiny cav@cryptopro.ru} & up-to-date \\ \hline - Serbian & Dejan Milosavljevic & {\tt\tiny dmilos@email.com} & 1.3.8 \\ + Serbian & Dejan Milosavljevic & {\tt\tiny dmilos@email.com} & up-to-date \\ \hline Slovak & Stanislav Kudl\'{a}\v{c} & {\tt\tiny skudlac@pobox.sk} & 1.2.18 \\ \hline diff --git a/doc/preprocessing.doc b/doc/preprocessing.doc index bce601a..883f8d2 100644 --- a/doc/preprocessing.doc +++ b/doc/preprocessing.doc @@ -74,8 +74,30 @@ and specify the macro definitions after the \ref cfg_predefined "PREDEFINED" or \ref cfg_expand_as_defined "EXPAND_AS_DEFINED" tag. -As an example, suppose you have the following obfuscated code fragment -of an abstract base class called \c IUnknown: +A typically example where some help from the preprocessor is needed is +when dealing with Microsoft's __declspec language extension. Here is an +example function. + +\verbatim +extern "C" void __declspec(dllexport) ErrorMsg( String aMessage,...); +\endverbatim + +When nothing is done, doxygen will be confused and see __declspec as +some sort of function. To help doxygen one typically uses the following +preprocessor settings: + +\verbatim +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +PREDEFINED = __declspec(x)= +\endverbatim + +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 class called \c IUnknown: \verbatim /*! A reference to an IID */ diff --git a/doc/translator_report.txt b/doc/translator_report.txt index 9a6959f..ab1718b 100644 --- a/doc/translator_report.txt +++ b/doc/translator_report.txt @@ -1,4 +1,4 @@ -(1.3.9) +(1.3.9.1) Doxygen supports the following 30 languages (sorted alphabetically): @@ -8,7 +8,7 @@ German, Greek, Hungarian, Italian, Japanese (+En), Korean (+En), Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian. -Of them, 13 translators are up-to-date, 17 translators are based on +Of them, 14 translators are up-to-date, 16 translators are based on some adapter class, and 2 are English based. ---------------------------------------------------------------------- @@ -29,6 +29,7 @@ still may be some details listed even for them: TranslatorItalian TranslatorPolish TranslatorRussian + TranslatorSerbian TranslatorSwedish ---------------------------------------------------------------------- @@ -42,7 +43,6 @@ must be implemented to become up-to-date: TranslatorDanish 1.3.9 6 methods to implement TranslatorAfrikaans 1.3.9 6 methods to implement TranslatorSpanish 1.3.8 7 methods to implement - TranslatorSerbian 1.3.8 7 methods to implement TranslatorLithuanian 1.3.8 7 methods to implement TranslatorKorean 1.3.8 7 methods to implement TranslatorChinesetraditional 1.3.8 7 methods to implement @@ -452,22 +452,6 @@ TranslatorRomanian (TranslatorAdapter_1_2_16) 22 methods to implement virtual QCString trRTFTableOfContents() -TranslatorSerbian (TranslatorAdapter_1_3_8) 7 methods to implement ------------------ - - Implements 194 of the required methods. - - Missing methods (should be implemented): - - virtual QCString trDirIndex() - virtual QCString trDirDocumentation() - virtual QCString trDirectories() - virtual QCString trDirDescription() - virtual QCString trSourceFile(QCString & filename) - virtual QCString trDirReference(const char * dirName) - virtual QCString trDir(bool first_capital, bool singular) - - TranslatorSlovak (TranslatorAdapter_1_2_18) 20 methods to implement ---------------- |
