diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/autolink.doc | 2 | ||||
| -rw-r--r-- | doc/changelog.doc | 2 | ||||
| -rw-r--r-- | doc/commands.doc | 111 | ||||
| -rw-r--r-- | doc/custcmd.doc | 2 | ||||
| -rw-r--r-- | doc/customize.doc | 9 | ||||
| -rw-r--r-- | doc/docblocks.doc | 2 | ||||
| -rw-r--r-- | doc/doxygen.1 | 4 | ||||
| -rw-r--r-- | doc/doxygen_manual.tex | 7 | ||||
| -rw-r--r-- | doc/doxyindexer.1 | 2 | ||||
| -rw-r--r-- | doc/doxysearch.1 | 4 | ||||
| -rw-r--r-- | doc/faq.doc | 2 | ||||
| -rw-r--r-- | doc/install.doc | 2 | ||||
| -rw-r--r-- | doc/starting.doc | 2 | ||||
| -rw-r--r-- | doc/xmlcmds.doc | 3 |
14 files changed, 96 insertions, 58 deletions
diff --git a/doc/autolink.doc b/doc/autolink.doc index 98556c5..ff468e4 100644 --- a/doc/autolink.doc +++ b/doc/autolink.doc @@ -16,7 +16,7 @@ */ /*! \page autolink Automatic link generation - \tableofcontents + \tableofcontents{html,latex} Most documentation systems have special `see also' sections where links to other pieces of documentation can be inserted. diff --git a/doc/changelog.doc b/doc/changelog.doc index 1d4eeba..0b245b6 100644 --- a/doc/changelog.doc +++ b/doc/changelog.doc @@ -1,5 +1,5 @@ /** \page changelog Changelog -\tableofcontents +\tableofcontents{html,latex} \section log_1_8 1.8 Series \subsection log_1_8_14 Release 1.8.14 diff --git a/doc/commands.doc b/doc/commands.doc index 1c7e7cf..a630aac 100644 --- a/doc/commands.doc +++ b/doc/commands.doc @@ -442,14 +442,15 @@ Structural indicators \endlatexonly </p><hr> -\section cmdexample \\example <file-name> +\section cmdexample \\example[{lineno}] <file-name> \addindex \\example Indicates that a comment block contains documentation for a source code - example. The name of the source file is \<file-name\>. The text of - this file will be included in the documentation, just after the - documentation contained in the comment block. All examples are placed - in a list. The source code is scanned for documented members and classes. + example. The name of the source file is \<file-name\>. + The contents of this file will be included in the documentation, just after the + documentation contained in the comment block. + You can add option `{lineno}` to enable line numbers for the example if desired. + All examples are placed in a list. The source code is scanned for documented members and classes. If any are found, the names are cross-referenced with the documentation. Source files or directories can be specified using the \ref cfg_example_path "EXAMPLE_PATH" @@ -1108,6 +1109,14 @@ Structural indicators This command is equivalent to \ref cmdfn "\\fn", \ref cmdproperty "\\property", and \ref cmdtypedef "\\typedef". + Note that for PHP one can also specify the type of the variable. + The syntax is similar as for the `phpDocumentor` but the description has to start + at the next line, i.e. +\verbatim +@var datatype $varname +Description +\endverbatim + \sa section \ref cmdfn "\\fn", \ref cmdproperty "\\property", and \ref cmdtypedef "\\typedef". <hr> @@ -1281,6 +1290,8 @@ The output will be different depending on whether or not \ref cfg_enabled_sectio contains \c TEST, or \c DEV \sa sections \ref cmdendcond "\\endcond" and \ref cfg_enabled_sections "ENABLED_SECTIONS". + \note Due to the moment of parsing the \c \\cond and \ref cmdendcond "\\endcond" commands cannot + be used in \ref cfg_aliases "ALIASES". <hr> \section cmdcopyright \\copyright { copyright description } @@ -1357,6 +1368,8 @@ contains \c TEST, or \c DEV Ends a conditional section that was started by \ref cmdcond "\\cond". \sa section \ref cmdcond "\\cond". + \note Due to the moment of parsing the \c \\endcond and \ref cmdcond "\\cond" commands cannot + be used in \ref cfg_aliases "ALIASES". <hr> \section cmdendif \\endif @@ -1571,7 +1584,7 @@ void setPosition(double x,double y,double z,double t) Note that for PHP one can also specify the type (or types if you separate them with a pipe symbol) which are allowed for a parameter (as this is not part of the definition). - The syntax is the same as for phpDocumentor, i.e. + The syntax is the same as for the `phpDocumentor`, i.e. \verbatim @param datatype1|datatype2 $paramname description \endverbatim @@ -2016,15 +2029,23 @@ Make sure you have first read \ref intro "the introduction". \endverbatim <hr> -\section cmdtableofcontents \\tableofcontents +\section cmdtableofcontents \\tableofcontents['{'[option[:level]][,option[:level]]*'}'] \addindex \\tableofcontents Creates a table of contents at the top of a page, listing all - sections and subsections in the page. + sections and subsections in the page. The `option` can be `HTML` or `LaTeX` + or `XML`. When a `level` is specified this means the maximum nesting level + that is shown. The value of `level` should be in the range 1..5, values outside + this range are considered to be 5. In case no `level` is specified `level` is + set to 5 (show all) + In case no `option`. is specified \c \\tableofcontents acts as if just the + `option` `HTML` was specified. In case of multiple \c \\tableofcontents + commands in a page the `option`(s) will be used additional to the already + specified `option`(s), but only the last `level` of an `option` is valid. \warning This command only works inside related page documentation and \e not in other documentation blocks and only has effect in the - HTML output! + the specified output! <hr> \section cmdsection \\section <section-name> (section title) @@ -2131,16 +2152,12 @@ Commands for displaying examples for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. \endlatexonly - Alternatively, the \ref cmdsnippet "\\snippet" command can be used to - include only a fragment of a source file. For this to work the - fragment has to be marked. - \sa sections \ref cmdline "\\line", \ref cmdskip "\\skip", \ref cmdskipline "\\skipline", \ref cmduntil "\\until", and \ref cmdinclude "\\include". </p><hr> -\section cmdinclude \\include <file-name> +\section cmdinclude \\include[{lineno|doc}] <file-name> \addindex \\include This command can be used to include a source file as a block of code. @@ -2174,33 +2191,38 @@ 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. + + \note Some that when using the `{doc}` option, + commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with + this command due to the moment of parsing. + + \note The included documentation should not have comment signs in it as they will appear + in the documentation as well. + \sa sections \ref cmdexample "\\example", \ref cmddontinclude "\\dontinclude", - \ref cmdverbatim "\\verbatim" and \ref cmdincludedoc "\\includedoc". + \ref cmdverbatim "\\verbatim", \ref cmdincludedoc "\\includedoc", and + \ref cmdsnippet "\\snippet". <hr> \section cmdincludelineno \\includelineno <file-name> \addindex \\includelineno - This command works the same way as \ref cmdinclude "\\include", but will add line - numbers to the included file. + This command is obsolete and is still supported for backward compatibility reasons, + it works the same way as \ref cmdinclude "\\include{lineno}" - \sa sections \ref cmdinclude "\\include" and \ref cmdsnippetlineno "\\snippetlineno". + \sa sections \ref cmdinclude "\\include{lineno}". <hr> \section cmdincludedoc \\includedoc <file-name> \addindex \\includedoc - This command works the same way as \ref cmdinclude "\\include", but it will include - the content of the file as if it were at the place where this command is called. - The result is that the content is parsed by doxygen and placed in the documentation. + This command is obsolete and is still supported for backward compatibility reasons, + it works the same way as \ref cmdinclude "\\include{doc}" - \note Some commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with - this command due to the moment of parsing. - - \note The included documentation should not have comment signs in it as they will appear - in the documentation as well. - - \sa section \ref cmdinclude "\\include". + \sa section \ref cmdinclude "\\include{doc}". <hr> \section cmdline \\line ( pattern ) @@ -2258,7 +2280,7 @@ Commands for displaying examples See section \ref cmddontinclude "\\dontinclude" for an example. <hr> -\section cmdsnippet \\snippet <file-name> ( block_id ) +\section cmdsnippet \\snippet[{lineno|doc}] <file-name> ( block_id ) \addindex \\snippet Where the \ref cmdinclude "\\include" command can be used to include @@ -2301,34 +2323,37 @@ 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. + + \note Some that when using the `{doc}` option, + commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with + this command due to the moment of parsing. + + \note The included documentation should not have comment signs in it as they will appear + in the documentation as well. + see section \ref cmddontinclude "\\dontinclude" for an alternative way to include fragments of a source file that does not require markers. - \sa section \ref cmdsnippetdoc "\\snippetdoc" and \ref cmdsnippetlineno "\\snippetlineno". <hr> \section cmdsnippetlineno \\snippetlineno <file-name> ( block_id ) \addindex \\snippetlineno - This command works the same way as \ref cmdsnippet "\\snippet", but will add line - numbers to the included snippet. + This command is obsolete and is still supported for backward compatibility reasons, + it works the same way as \ref cmdsnippet "\\snippet{lineno}" - \sa sections \ref cmdsnippet "\\snippet" and \ref cmdincludelineno "\\includelineno". + \sa sections \ref cmdsnippet "\\snippet{lineno}" <hr> \section cmdsnippetdoc \\snippetdoc <file-name> ( block_id ) \addindex \\snippetdoc - This command works the same way as \ref cmdsnippet "\\snippet", but it will include - the content of the file between the `block-id`s as if it were at the place where this command is called. - The result is that the content is parsed by doxygen and placed in the documentation. - - \note Some commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with - this command due to the moment of parsing. - - \note The included documentation should not have comment signs in it as they will appear - in the documentation as well. + This command is obsolete and is still supported for backward compatibility reasons, + it works the same way as \ref cmdsnippet "\\snippet{doc}" - \sa section \ref cmdsnippet "\\snippet" and \ref cmdincludedoc "\\includedoc". + \sa section \ref cmdsnippet "\\snippet{doc}" and \ref cmdinclude "\\include{doc}". <hr> \section cmduntil \\until ( pattern ) diff --git a/doc/custcmd.doc b/doc/custcmd.doc index de9a30d..acc0224 100644 --- a/doc/custcmd.doc +++ b/doc/custcmd.doc @@ -16,7 +16,7 @@ */ /*! \page custcmd Custom Commands -\tableofcontents +\tableofcontents{html,latex} Doxygen provides a large number of \ref commands "special commands", \ref xmlcmds "XML commands", and \ref htmlcmds "HTML commands". diff --git a/doc/customize.doc b/doc/customize.doc index e2d53db..7b2729d 100644 --- a/doc/customize.doc +++ b/doc/customize.doc @@ -16,7 +16,7 @@ */ /*! \page customize Customizing the output -\tableofcontents +\tableofcontents{html,latex} Doxygen provides various levels of customization. The section \ref minor_tweaks "Minor Tweaks" discusses what to @@ -289,7 +289,12 @@ The following generic elements are possible for each page: <dt>\c detaileddescription <dd>Represents the detailed description on a page. <dt>\c authorsection - <dd>Represents the author section of a page (only used for man pages). + <dd>Represents the author section of a page (only used for man pages). This is + a separate section for man pages with a text like: + `Generated automatically by Doxygen for My Project from the source code.` + This should not be misinterpreted with the doxygen commands \ref cmdauthor + "\\author" or \ref cmdauthors "\\authors" that generate an author paragraph + inside a detailed description. <dt>\c memberdecl <dd>Represents the quick overview of members on a page (member declarations). This elements has child elements per type of member list. diff --git a/doc/docblocks.doc b/doc/docblocks.doc index e72ce95..f02e55b 100644 --- a/doc/docblocks.doc +++ b/doc/docblocks.doc @@ -15,7 +15,7 @@ * */ /*! \page docblocks Documenting the code -\tableofcontents +\tableofcontents{html,latex} This chapter covers two topics: 1. How to put comments in your code such that doxygen incorporates them in diff --git a/doc/doxygen.1 b/doc/doxygen.1 index 1deb7b6..5ac287e 100644 --- a/doc/doxygen.1 +++ b/doc/doxygen.1 @@ -3,7 +3,7 @@ doxygen \- documentation system for various programming languages .SH DESCRIPTION Doxygen is a documentation system for C++, C, Java, Objective-C, IDL -(Corba and Microsoft flavors) and to some extent PHP, C#, and D. +(Corba and Microsoft flavors), Fortran, Python, VHDL and to some extent PHP, C#, and D. .PP You can use doxygen in a number of ways: .TP @@ -25,7 +25,7 @@ If - is used for configName doxygen will read from standard input. .TP 4) Use doxygen to generate a template file controlling the layout of the generated documentation: .IP -doxygen -l layoutFileName.xml +doxygen -l [layoutFileName.xml] .TP 5) Use doxygen to generate a template style sheet file for RTF, HTML or Latex. .TP diff --git a/doc/doxygen_manual.tex b/doc/doxygen_manual.tex index 3e4cd49..95e1ed6 100644 --- a/doc/doxygen_manual.tex +++ b/doc/doxygen_manual.tex @@ -70,9 +70,13 @@ \hfuzz=15pt \setlength{\emergencystretch}{15pt} \setlength{\parindent}{0pt} -\setlength{\parskip}{0.2cm} +\newcommand{\doxynormalparskip}{\setlength{\parskip}{0.2cm}} +\newcommand{\doxytocparskip}{\setlength{\parskip}{0.2cm}} +\doxynormalparskip \hbadness=750 \tolerance=750 +\usepackage{etoc} +\etocsettocstyle{\doxytocparskip}{\doxynormalparskip} \begin{document} \pagenumbering{alph} \begin{titlepage} @@ -85,6 +89,7 @@ Written by Dimitri van Heesch\\[2ex] \end{titlepage} \clearemptydoublepage \pagenumbering{Roman} +\chapter*{Contents} \tableofcontents \clearemptydoublepage \pagenumbering{arabic} diff --git a/doc/doxyindexer.1 b/doc/doxyindexer.1 index ae4b282..b0d46d0 100644 --- a/doc/doxyindexer.1 +++ b/doc/doxyindexer.1 @@ -3,7 +3,7 @@ doxyindexer \- creates a search index from raw search data .SH SYNOPSIS .B doxyindexer -[\fI-o output_dir\fR] \fIsearchdata.xml \fR[\fIsearchdata2.xml\fR...] ] +[\fI-o output_dir\fR] \fIsearchdata.xml \fR[\fIsearchdata2.xml\fR...] .SH DESCRIPTION Generates a search index called \fBdoxysearch.db\fR from one or more search data files produced by doxygen. Use diff --git a/doc/doxysearch.1 b/doc/doxysearch.1 index a00124f..a26107b 100644 --- a/doc/doxysearch.1 +++ b/doc/doxysearch.1 @@ -2,10 +2,10 @@ .SH NAME doxysearch.cgi \- search engine used for searching in doxygen documentation. .SH SYNOPSIS -.B doxyindexer.cgi +.B doxysearch.cgi .SH DESCRIPTION CGI binary that is used by doxygen generated HTML output to search for words. The tool uses the search index called \fBdoxysearch.db\fR produced by doxyindexer. .SH SEE ALSO -doxygen(1), doxysearch(1), doxywizard(1). +doxygen(1), doxyindexer(1), doxywizard(1). diff --git a/doc/faq.doc b/doc/faq.doc index a91a2f5..e9c93d8 100644 --- a/doc/faq.doc +++ b/doc/faq.doc @@ -16,7 +16,7 @@ */ /*! \page faq Frequently Asked Questions -\tableofcontents +\tableofcontents{html,latex} \section faq_index How to get information on the index page in HTML? diff --git a/doc/install.doc b/doc/install.doc index f981431..497a0c0 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -17,7 +17,7 @@ /*! \page install Installation \addindex installation -\tableofcontents +\tableofcontents{html,latex} First go to the <a href="http://www.doxygen.org/download.html">download</a> page diff --git a/doc/starting.doc b/doc/starting.doc index e39aa25..0765a3b 100644 --- a/doc/starting.doc +++ b/doc/starting.doc @@ -15,7 +15,7 @@ * */ /*! \page starting Getting started -\tableofcontents +\tableofcontents{html,latex} The executable \c doxygen is the main program that parses the sources and generates the documentation. See section \ref doxygen_usage for more diff --git a/doc/xmlcmds.doc b/doc/xmlcmds.doc index 501bf91..848858d 100644 --- a/doc/xmlcmds.doc +++ b/doc/xmlcmds.doc @@ -70,6 +70,9 @@ Here is the list of tags supported by doxygen: <li><tt>\<typeparamref name="paramName"\></tt> Refers to a parameter with name "paramName". Similar to using \ref cmda "\\a". <li><tt>\<value\></tt> Identifies a property. Ignored by doxygen. +<li><tt>\<![CDATA[...]]\></tt> The text inside this tag (on the ...) is handled as normal + doxygen comment except for the XML special characters `<`, `>` and + `&` that are used as if they were escaped. </ul> Here is an example of a typical piece of code using some of the above commands: |