diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Doxyfile | 1 | ||||
| -rw-r--r-- | doc/commands.doc | 79 | ||||
| -rw-r--r-- | doc/docblocks.doc | 19 | ||||
| -rw-r--r-- | doc/doxygen_manual.css | 4 | ||||
| -rw-r--r-- | doc/doxygen_manual.tex | 58 | ||||
| -rw-r--r-- | doc/translator.py | 6 |
6 files changed, 113 insertions, 54 deletions
diff --git a/doc/Doxyfile b/doc/Doxyfile index 4c0a19d..7697d70 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -45,7 +45,6 @@ EXAMPLE_PATH = ../examples RECURSIVE = NO TAGFILES = ALLEXTERNALS = NO -PERL_PATH = /usr/bin/perl SEARCHENGINE = NO PDF_HYPERLINKS = YES USE_PDFLATEX = YES diff --git a/doc/commands.doc b/doc/commands.doc index 0e66c1d..6c8b696 100644 --- a/doc/commands.doc +++ b/doc/commands.doc @@ -29,9 +29,14 @@ Each argument has a certain range: <li>If (round) braces are used the argument extends until the end of the line on which the command was found. <li>If {curly} braces are used the argument extends until the next paragraph. - Paragraphs are delimited by a blank line or by a section indicator. + Paragraphs are delimited by a blank line or by a section indicator. Note that + {curly} braces are also used for command options, here the braces are mandatory + and just 'normal' characters. The starting curly brace has to directly follow + the command, so without whitspace. </ul> -If in addition to the above argument specifiers [square] brackets are used the argument is optional. +If in addition to the above argument specifiers [square] brackets are used the argument +is optional, unless they are placed between quotes in that case they are a mandatory +part of the command argument. Here is an alphabetically sorted list of all commands with references to their documentation: @@ -445,7 +450,7 @@ Structural indicators for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. \endlatexonly -</p><hr> +<hr> \section cmddef \\def <name> \addindex \\def @@ -463,7 +468,7 @@ Structural indicators for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. \endlatexonly -</p><hr> +<hr> \section cmddefgroup \\defgroup <name> (group title) \addindex \\defgroup @@ -515,8 +520,8 @@ Structural indicators for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. \endlatexonly -</p><hr> -\section cmdexample \\example[{lineno}] <file-name> +<hr> +\section cmdexample \\example['{lineno}'] <file-name> \addindex \\example Indicates that a comment block contains documentation for a source code @@ -553,7 +558,7 @@ Structural indicators \sa section \ref cmdinclude "\\include". -</p><hr> +<hr> \section cmdendinternal \\endinternal \addindex \\endinternal @@ -612,7 +617,7 @@ Structural indicators \note In the above example \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" has been set to \c YES in the configuration file. -</p><hr> +<hr> \section cmdfn \\fn (function declaration) \addindex \\fn @@ -650,7 +655,7 @@ Structural indicators \sa sections \ref cmdvar "\\var", \ref cmdproperty "\\property", and \ref cmdtypedef "\\typedef". -</p><hr> +<hr> \section cmdheaderfile \\headerfile <header-file> [<header-name>] \addindex \\headerfile @@ -836,7 +841,7 @@ Structural indicators \ref cmdpublic "\\public", \ref cmdprotected "\\protected" and \ref cmdprivate "\\private". -</p><hr> +<hr> \section cmdname \\name [(header)] \addindex \\name @@ -904,7 +909,7 @@ Structural indicators for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. \endlatexonly -</p><hr> +<hr> \section cmdpackage \\package <name> \addindex \\package @@ -945,7 +950,7 @@ Structural indicators \ref cmdsubsection "\\subsection", and section \ref cmdref "\\ref". -</p><hr> +<hr> \section cmdprivate \\private \addindex \\private @@ -1092,7 +1097,7 @@ Structural indicators for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. \endlatexonly -</p><hr> +<hr> \section cmdrelated \\related <name> \addindex \\related @@ -1255,7 +1260,7 @@ Section indicators for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. \endlatexonly -</p><hr> +<hr> \section cmdauthors \\authors { list of authors } \addindex \\authors @@ -1606,8 +1611,8 @@ ALIASES = "english=\if english" \ for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. \endlatexonly -</p><hr> -\section cmdparam \\param [(dir)] <parameter-name> { parameter description } +<hr> +\section cmdparam \\param '['dir']' <parameter-name> { parameter description } \addindex \\param Starts a parameter description for a function parameter with name @@ -1616,7 +1621,7 @@ ALIASES = "english=\if english" \ the documentation of this (or any other) parameter is missing or not present in the function declaration or definition. - The \c \\param command has an optional attribute, (dir), specifying the direction + The \c \\param command has an optional attribute, `dir`, specifying the direction of the parameter. Possible values are "[in]", "[in,out]", and "[out]", note the [square] brackets in this description. When a parameter is both input and output, [in,out] is used as attribute. @@ -2186,7 +2191,7 @@ Commands for displaying examples \htmlonly</p></center><p>\endhtmlonly <hr> -\section cmddontinclude \\dontinclude <file-name> +\section cmddontinclude \\dontinclude['{lineno}'] <file-name> \addindex \\dontinclude This command can be used to parse a source file without actually @@ -2197,6 +2202,8 @@ Commands for displaying examples \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file. + You can add option `{lineno}` to enable line numbers for the included code if desired. + The class and member declarations and definitions inside the code fragment are 'remembered' during the parsing of the comment block that contained the \c \\dontinclude command. @@ -2224,8 +2231,8 @@ Commands for displaying examples \ref cmdskipline "\\skipline", \ref cmduntil "\\until", and \ref cmdinclude "\\include". -</p><hr> -\section cmdinclude \\include[{lineno|doc}] <file-name> +<hr> +\section cmdinclude \\include['{'option'}'] <file-name> \addindex \\include This command can be used to include a source file as a block of code. @@ -2259,9 +2266,9 @@ Commands for displaying examples \note Doxygen's special commands do not work inside blocks of code. It is allowed to nest C-style comments inside a code block though. - You can add option `{lineno}` to enable line numbers for the included code if desired. - - You can add option `{doc}` to treat the file as documentation rather than code. + The `option` can either be `lineno` or `doc`. + The `option` `lineno` can be used to enable line numbers for the included code if desired. + The `option` `doc` can be used to treat the file as documentation rather than code. \note Some that when using the `{doc}` option, commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with @@ -2348,7 +2355,7 @@ Commands for displaying examples See section \ref cmddontinclude "\\dontinclude" for an example. <hr> -\section cmdsnippet \\snippet[{lineno|doc}] <file-name> ( block_id ) +\section cmdsnippet \\snippet['{'option'}'] <file-name> ( block_id ) \addindex \\snippet Where the \ref cmdinclude "\\include" command can be used to include @@ -2391,9 +2398,9 @@ Commands for displaying examples Note also that the [block_id] markers should appear exactly twice in the source file. - You can add option `{lineno}` to enable line numbers for the snippet if desired. - - You can add option `{doc}` to treat the file as documentation rather than code. + The `option` can either be `lineno` or `doc`. + The `option` `lineno` can be used to enable line numbers for the included code if desired. + The `option` `doc` can be used to treat the file as documentation rather than code. \note Some that when using the `{doc}` option, commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with @@ -2572,7 +2579,7 @@ Commands for visual enhancements To have multiple words in typewriter font use \<tt\>multiple words\</tt\>. <hr> -\section cmdcode \\code [ '{'<word>'}'] +\section cmdcode \\code['{'<word>'}'] \addindex \\code Starts a block of code. A code block is treated differently @@ -2776,9 +2783,9 @@ See also the \ref emojisup "emoji support page" for details. \note The text fragment should only include the part of the message sequence chart that is - within the <code>msc {...}</code> block. - \note You need to install the <code>mscgen</code> tool, if you want to use this - command. + within the <code>msc {...}</code> block (this is different from + \ref cmdmscfile "\\mscfile"). + \note mscgen is now built in into doxygen Here is an example of the use of the \c \\msc command. \code @@ -2916,7 +2923,7 @@ class Receiver The first argument specifies the file name of the image. doxygen will look for files in the paths (or files) that you specified after the \ref cfg_mscfile_dirs "MSCFILE_DIRS" tag. - If the msc file is found it will be used as an input file to the mscgen tool. + If the msc file is found it will be used as an input file to the built in mscgen tool. The resulting image will be put into the correct output directory. If the msc file name contains spaces you'll have to put quotes ("...") around it. @@ -2931,6 +2938,10 @@ class Receiver \ref image_sizeindicator "Size indication" with the \ref cmdimage "\\image" command. + \note The text fragment should include the part message of the + sequence chart as well as the starting `msc {` and ending `}` + (this is different from \ref cmdmsc "\\msc"). + \sa section \ref cmdmsc "\\msc". <hr> @@ -3150,7 +3161,7 @@ class Receiver \ref cmdhtmlinclude "\\htmlinclude". <hr> -\section cmdimage \\image['{'[option]'}'] <format> <file> ["caption"] [<sizeindication>=<size>] +\section cmdimage \\image['{'option'}'] <format> <file> ["caption"] [<sizeindication>=<size>] \addindex \\image Inserts an image into the documentation. This command is format @@ -3522,10 +3533,8 @@ browser generator. Do \e not use these commands in your own documentation. \htmlonly -</p> Go to the <a href="htmlcmds.html">next</a> section or return to the <a href="index.html">index</a>. -<p> \endhtmlonly */ diff --git a/doc/docblocks.doc b/doc/docblocks.doc index d4eab5d..9d14f6e 100644 --- a/doc/docblocks.doc +++ b/doc/docblocks.doc @@ -123,6 +123,25 @@ or ///////////////////////////////////////////////// \endverbatim +or + +\verbatim +/************************************************ + * ... text + ***********************************************/ +\endverbatim + +as long as JAVADOC_BANNER = YES is used. +\include javadoc-banner.h + \htmlonly + Click <a href="examples/javadoc-banner/html/index.html">here</a> + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + \latexonly + See \hyperlink{javadoc_banner_example}{Javadoc Banner example} + for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. + \endlatexonly + </ol> For the brief description there are also several possibilities: diff --git a/doc/doxygen_manual.css b/doc/doxygen_manual.css index 87d560c..1c42e1b 100644 --- a/doc/doxygen_manual.css +++ b/doc/doxygen_manual.css @@ -49,11 +49,13 @@ dt { font-weight: bold; } -div.multicol { +ul.multicol { -moz-column-gap: 1em; -webkit-column-gap: 1em; + column-gap: 1em; -moz-column-count: 3; -webkit-column-count: 3; + column-count: 3; } p.startli, p.startdd { diff --git a/doc/doxygen_manual.tex b/doc/doxygen_manual.tex index 1a44574..bf269d2 100644 --- a/doc/doxygen_manual.tex +++ b/doc/doxygen_manual.tex @@ -57,6 +57,16 @@ \usepackage{amssymb} \usepackage{doxygen} \usepackage{manual} +%% +\makeatletter +\newenvironment{DoxygenSubAppendix}{% + \renewcommand{\doxysection}{\@ifstar{\doxysubsection@star}{\doxysubsection@nostar}}% + \renewcommand{\doxysubsection}{\@ifstar{\doxysubsubsection@star}{\doxysubsubsection@nostar}} + \renewcommand{\doxysubsubsection}{\@ifstar{\doxyparagraph@star}{\doxyparagraph@nostar}} + \renewcommand{\doxyparagraph}{\@ifstar{\doxysubparagraph@star}{\doxysubparagraph@nostar}} +}{} +\makeatother +%% \newcommand{\+}{\discretionary{\mbox{\scriptsize$\hookleftarrow$}}{}{}} \lstset{language=C++,inputencoding=utf8,basicstyle=\footnotesize,breaklines=true,breakatwhitespace=true,tabsize=8,numbers=left } \makeindex @@ -147,22 +157,42 @@ Written by Dimitri van Heesch\\[2ex] \subinputfrom{../html/examples/group/latex/}{refman_doc} \chapter{Member Groups Example}\label{memgrp_example}\hypertarget{memgrp_example}{} \subinputfrom{../html/examples/memgrp/latex/}{refman_doc} -\chapter{After Block Example}\label{afterdoc_example}\hypertarget{afterdoc_example}{} -\subinputfrom{../html/examples/afterdoc/latex/}{refman_doc} -\chapter{QT Style Example}\label{qtstyle_example}\hypertarget{qtstyle_example}{} -\subinputfrom{../html/examples/qtstyle/latex/}{refman_doc} -\chapter{Javadoc Style Example}\label{jdstyle_example}\hypertarget{jdstyle_example}{} -\subinputfrom{../html/examples/jdstyle/latex/}{refman_doc} +\chapter{Style Examples} + \doxysection{After Block Example}\label{afterdoc_example}\hypertarget{afterdoc_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/afterdoc/latex/}{refman_doc} + \end{DoxygenSubAppendix} + \doxysection{QT Style Example}\label{qtstyle_example}\hypertarget{qtstyle_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/qtstyle/latex/}{refman_doc} + \end{DoxygenSubAppendix} + \doxysection{Javadoc Style Example}\label{jdstyle_example}\hypertarget{jdstyle_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/jdstyle/latex/}{refman_doc} + \end{DoxygenSubAppendix} + \doxysection{Javadoc Banner Example}\label{javadoc_banner_example}\hypertarget{javadoc_banner_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/javadoc-banner/latex/}{refman_doc} + \end{DoxygenSubAppendix} \chapter{Structural Commands Example}\label{structcmd_example}\hypertarget{structcmd_example}{} \subinputfrom{../html/examples/structcmd/latex/}{refman_doc} -\chapter{Python Docstring Example}\label{python_example}\hypertarget{python_example}{} -\subinputfrom{../html/examples/docstring/latex/}{refman_doc} -\chapter{Python Example}\label{py_example}\hypertarget{py_example}{} -\subinputfrom{../html/examples/pyexample/latex/}{refman_doc} -\chapter{VHDL Example}\label{vhdl_example}\hypertarget{vhdl_example}{} -\subinputfrom{../html/examples/mux/latex/}{refman_doc} -\chapter{Tcl Example}\label{tcl_example}\hypertarget{tcl_example}{} -\subinputfrom{../html/examples/tclexample/latex/}{refman_doc} +\chapter{Language Examples} + \doxysection{Python Docstring Example}\label{python_example}\hypertarget{python_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/docstring/latex/}{refman_doc} + \end{DoxygenSubAppendix} + \doxysection{Python Example}\label{py_example}\hypertarget{py_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/pyexample/latex/}{refman_doc} + \end{DoxygenSubAppendix} + \doxysection{VHDL Example}\label{vhdl_example}\hypertarget{vhdl_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/mux/latex/}{refman_doc} + \end{DoxygenSubAppendix} + \doxysection{Tcl Example}\label{tcl_example}\hypertarget{tcl_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/tclexample/latex/}{refman_doc} + \end{DoxygenSubAppendix} \chapter{Class Example}\label{class_example}\hypertarget{class_example}{} \subinputfrom{../html/examples/class/latex/}{refman_doc} diff --git a/doc/translator.py b/doc/translator.py index 2246c08..ed001bb 100644 --- a/doc/translator.py +++ b/doc/translator.py @@ -1821,9 +1821,9 @@ class TrManager: tplDic['numLangStr'] = str(self.numLang)
# Define templates for HTML table parts of the documentation.
- htmlTableTpl = '''\
+ htmlTableTpl = '''
\\htmlonly
- </p>
+ </p>
<table align="center" cellspacing="0" cellpadding="0" border="0">
<tr bgcolor="#000000">
<td>
@@ -1842,7 +1842,7 @@ class TrManager: </td>
</tr>
</table>
- <p>
+ <p>
\\endhtmlonly
'''
htmlTableTpl = textwrap.dedent(htmlTableTpl)
|