diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Doxyfile | 1 | ||||
| -rw-r--r-- | doc/commands.doc | 51 | ||||
| -rw-r--r-- | doc/docblocks.doc | 19 | ||||
| -rw-r--r-- | doc/doxygen_manual.tex | 68 | ||||
| -rw-r--r-- | doc/faq.doc | 7 | ||||
| -rw-r--r-- | doc/install.doc | 2 | ||||
| -rw-r--r-- | doc/trouble.doc | 2 |
7 files changed, 111 insertions, 39 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 ae27a7a..48991fb 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: @@ -516,7 +521,7 @@ Structural indicators \endlatexonly <hr> -\section cmdexample \\example[{lineno}] <file-name> +\section cmdexample \\example['{lineno}'] <file-name> \addindex \\example Indicates that a comment block contains documentation for a source code @@ -844,7 +849,7 @@ Structural indicators This command turns a comment block into a header definition of a member group. The comment block should be followed by a - <code>//\@{ ... //\@}</code> block containing the + <code>///\@{ ... ///\@}</code> block containing the members of the group. See section \ref memgroup for an example. @@ -1607,7 +1612,7 @@ ALIASES = "english=\if english" \ \endlatexonly <hr> -\section cmdparam \\param [(dir)] <parameter-name> { parameter description } +\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[{lineno}] <file-name> +\section cmddontinclude \\dontinclude['{lineno}'] <file-name> \addindex \\dontinclude This command can be used to parse a source file without actually @@ -2227,7 +2232,7 @@ Commands for displaying examples \ref cmdinclude "\\include". <hr> -\section cmdinclude \\include[{lineno|doc}] <file-name> +\section cmdinclude \\include['{'option'}'] <file-name> \addindex \\include This command can be used to include a source file as a block of code. @@ -2261,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 @@ -2350,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 @@ -2393,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 @@ -2574,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 @@ -2778,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 @@ -2918,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. @@ -2933,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> @@ -3152,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 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.tex b/doc/doxygen_manual.tex index 1a44574..078bdea 100644 --- a/doc/doxygen_manual.tex +++ b/doc/doxygen_manual.tex @@ -14,6 +14,14 @@ \batchmode \documentclass{book} +%% moved from doxygen.sty due to workaround for LaTex 2019 version and unmaintained tabu package +\usepackage{ifthen} +\ifx\requestedLaTeXdate\undefined +\usepackage{array} +\else +\usepackage{array}[=2016-10-06] +\fi +%% \usepackage[a4paper,left=2.5cm,right=2.5cm,top=2.5cm,bottom=2.5cm]{geometry} \usepackage{makeidx} \usepackage{natbib} @@ -23,7 +31,7 @@ \usepackage{geometry} \usepackage{listings} \usepackage{color} -\usepackage{ifthen} +%%\usepackage{ifthen} %% moved to top due to workaround for LaTex 2019 version and unmaintained tabu package \usepackage[table]{xcolor} \PassOptionsToPackage{warn}{textcomp} \usepackage{textcomp} @@ -57,6 +65,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 +165,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/faq.doc b/doc/faq.doc index 88a1275..0ba9450 100644 --- a/doc/faq.doc +++ b/doc/faq.doc @@ -235,6 +235,13 @@ should send me a code fragment that triggers the message. To work around the problem, put some line-breaks into your file, split it up into smaller parts, or exclude it from the input using EXCLUDE. +Another way to work around this problem is to use the cmake command with the option: +``` +-Denlarge_lex_buffers=<size> +``` +where `<size>` is the new size of the input (`YY_BUF_SIZE`) and read (`YY_READ_BUF_SIZE`) buffer. +In case this option is not given the default value of 262144 (i.e. 256K) will be used. + \section faq_latex When running make in the latex directory I get "TeX capacity exceeded". Now what? You can edit the texmf.cfg file to increase the default values of the diff --git a/doc/install.doc b/doc/install.doc index 18ea44e..b711cd4 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -201,7 +201,7 @@ tar zxvf doxygen-x.y.z.src.tar.gz \endverbatim to unpack the sources (you can obtain \c tar from e.g. http://gnuwin32.sourceforge.net/packages.html). Alternatively you can use an unpack program, like 7-Zip (see https://www.7-zip.org/) -or use the build in unpack feature of modern Windows systems). +or use the built-in unpack feature of modern Windows systems). Now your environment is setup to generate the required project files for \c doxygen. diff --git a/doc/trouble.doc b/doc/trouble.doc index c490ae1..cb50399 100644 --- a/doc/trouble.doc +++ b/doc/trouble.doc @@ -20,7 +20,7 @@ <ul> <li>Doxygen is <em>not</em> a real compiler, it is only a lexical scanner. This means that it can and will not detect errors in your source code. -<li>Doxygen has a build in preprocessor, but this works slightly different than +<li>Doxygen has a built-in preprocessor, but this works slightly different than the C preprocessor. Doxygen assumes a header file is properly guarded against multiple inclusion, and that each include file is standalone (i.e. it could be placed at the top of a source file without causing compiler errors). As long as this is |