diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Doxyfile | 55 | ||||
| -rw-r--r-- | doc/autolink.doc | 4 | ||||
| -rw-r--r-- | doc/commands.doc | 67 | ||||
| -rw-r--r-- | doc/config.doc | 87 | ||||
| -rw-r--r-- | doc/doxygen_usage.doc | 12 | ||||
| -rw-r--r-- | doc/doxysearch_usage.doc | 8 | ||||
| -rw-r--r-- | doc/doxytag_usage.doc | 8 | ||||
| -rw-r--r-- | doc/features.doc | 23 | ||||
| -rw-r--r-- | doc/history.doc | 21 | ||||
| -rw-r--r-- | doc/htmlcmds.doc | 2 | ||||
| -rw-r--r-- | doc/index.doc | 4 | ||||
| -rw-r--r-- | doc/installdox_usage.doc | 2 | ||||
| -rw-r--r-- | doc/language.doc | 61 | ||||
| -rw-r--r-- | doc/starting.doc | 86 | ||||
| -rw-r--r-- | doc/trouble.doc | 7 |
15 files changed, 280 insertions, 167 deletions
diff --git a/doc/Doxyfile b/doc/Doxyfile index c7f9138..3c3e114 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -11,35 +11,36 @@ # # All output generated with Doxygen is not covered by this license. -PROJECT_NAME = -OUTPUT_DIRECTORY = .. -HTML_HEADER = -HTML_FOOTER = -QUIET = NO -WARNINGS = YES -DISABLE_INDEX = YES -EXTRACT_ALL = NO -EXTRACT_PRIVATE = NO -GENERATE_MAN = NO -GENERATE_LATEX = YES -GENERATE_HTML = YES +PROJECT_NAME = +OUTPUT_DIRECTORY = .. +HTML_HEADER = +HTML_FOOTER = +QUIET = NO +WARNINGS = YES +DISABLE_INDEX = YES +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +GENERATE_MAN = NO +GENERATE_LATEX = YES +GENERATE_HTML = YES +GENERATE_HTMLHELP = YES ENABLE_PREPROCESSING = NO -INPUT = index.doc install.doc starting.doc faq.doc trouble.doc \ +INPUT = index.doc install.doc starting.doc faq.doc trouble.doc \ history.doc features.doc \ doxygen_usage.doc doxytag_usage.doc doxysearch_usage.doc \ installdox_usage.doc output.doc autolink.doc \ config.doc commands.doc htmlcmds.doc language.doc -FILE_PATTERNS = *.cpp *.h *.doc -EXAMPLE_PATH = ../examples -RECURSIVE = NO -TAGFILES = -ALLEXTERNALS = NO -PERL_PATH = /usr/local/bin/perl -SEARCHENGINE = NO -CGI_NAME = search.cgi -CGI_URL = -DOC_URL = -DOC_ABSPATH = -BIN_ABSPATH = /usr/local/bin/ -EXT_DOC_PATHS = -PDF_HYPERLINKS = YES +FILE_PATTERNS = *.cpp *.h *.doc +EXAMPLE_PATH = ../examples +RECURSIVE = NO +TAGFILES = +ALLEXTERNALS = NO +PERL_PATH = /usr/local/bin/perl +SEARCHENGINE = NO +CGI_NAME = search.cgi +CGI_URL = +DOC_URL = +DOC_ABSPATH = +BIN_ABSPATH = /usr/local/bin/ +EXT_DOC_PATHS = +PDF_HYPERLINKS = YES diff --git a/doc/autolink.doc b/doc/autolink.doc index 900d819..2f0e04c 100644 --- a/doc/autolink.doc +++ b/doc/autolink.doc @@ -58,9 +58,9 @@ </ol> where n>0. - \par Notice 1: + \par Note 1: The patterns above should not contain spaces, tabs or newlines. - \par Notice 2: + \par Note 2: For JavaDoc compatibility a \c # may be used instead of a \c :: in the patterns above. diff --git a/doc/commands.doc b/doc/commands.doc index d391c2c..34853af 100644 --- a/doc/commands.doc +++ b/doc/commands.doc @@ -176,6 +176,17 @@ Doxygen. Unrecognized commands are treated as normal text. group of classes, files or namespaces. This can be used to categorize classes, files or namespaces, and document those categories. + + The \<name\> argument should an single word identifier. + + \par Example: + \verbinclude group.cpp + + \htmlonly + Click <a href="$(DOXYGEN_DOCDIR)/examples/group/html/modules.html">here</a> + for the corresponding HTML documentation that is generated by Doxygen. + \endhtmlonly + \sa section \ref cmdingroup "\\ingroup" <hr> @@ -197,7 +208,7 @@ Doxygen. Unrecognized commands are treated as normal text. If a comment block is located directly in front of an enum declaration, the \\enum comment may be omitted. - \par Notice: + \par Note: The type of an anonymous enum cannot be documented, but the values of an anonymous enum can. @@ -274,11 +285,12 @@ Doxygen. Unrecognized commands are treated as normal text. \sa section \ref cmdvar "\\var" and \ref cmdtypedef "\\typedef". <hr> -\subsection cmdingroup \ingroup <groupname> +\subsection cmdingroup \ingroup (<groupname> [<groupname> <groupname>]) \addindex \ingroup If the \\ingroup command is placed in a comment block of a - class, file or namespace, then it will be added to the group. + class, file or namespace, then it will be added to the group or + groups identified by \<groupname\>. \sa section \ref cmddefgroup "\\defgroup". @@ -345,10 +357,10 @@ Doxygen. Unrecognized commands are treated as normal text. Any other documentation that is inside the documentation block will by appended after the generated message. - \par Notice 1: + \par Note 1: You are responsible that there is indeed an earlier documented member that is overloaded by this one. - \par Notice 2: + \par Note 2: The \\overload command does not work inside a one-line comment. \par Example: \verbinclude examples/overload.cpp @@ -374,7 +386,7 @@ Doxygen. Unrecognized commands are treated as normal text. for the corresponding HTML documentation that is generated by Doxygen. \endhtmlonly - \par notice: + \par Note: The \<name\> argument consists of a combination of letters and number digits. If you wish to use upper case letters (e.g. \c MYPAGE1), or mixed case letters (e.g. \c MyPage1) in the \<name\> argument, you @@ -693,7 +705,7 @@ Doxygen. Unrecognized commands are treated as normal text. See section \ref autolink "\\autolink" for more information on automatically generated links and valid link-objects. - \b Notice: + \b Note: Keep in mind that links are only meaningful in HTML text; in \f$\mbox{\LaTeX}\f$ text, the link text is just written to the output. @@ -843,7 +855,7 @@ Doxygen. Unrecognized commands are treated as normal text. the example, is set to the start of the line following the line that is written (or to the end of the example if the pattern could not be found). - \par Notice: + \par Note: The command: \verbatim\skipline pattern\endverbatim is equivalent to: @@ -921,7 +933,7 @@ Doxygen. Unrecognized commands are treated as normal text. </ul><br> No other types of alignment are supported. - \par Notice: + \par Note: For nested lists, HTML commands should be used. <hr> @@ -1021,11 +1033,11 @@ Doxygen. Unrecognized commands are treated as normal text. endhtmlonly command. This command can be used to include HTML code that is too complex - for Doxygen (i.e. images, applets, java-scripts, and HTML tags that + for Doxygen (i.e. applets, java-scripts, and HTML tags that require attributes). You can use the \\latexonly and \\endlatexonly pair to provide a proper \f$\mbox{\LaTeX}\f$ alternative. - \b Notice: + \b Note: environment variables (like \$(HOME) ) are resolved inside a HTML-only block. @@ -1043,12 +1055,13 @@ Doxygen. Unrecognized commands are treated as normal text. The first argument specifies the output format. Currently, the following values are supported: \c html and \c latex. - The second argument specifies the path and file name of the image. - If a relative path is used, this will be relative to the directory to - which the output of the particular format is written. - For the html format you may also - specify an URL. If the name contains spaces you'll have to put - quotes (") around it. + The second 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_image_path "IMAGE_PATH" tag and filter those files through the patterns + you specified after the \ref cfg_image_patterns "IMAGE_PATTERNS" tag. + If the image is found it + will be copied to the correct output directory. + If the image name contains spaces you'll have to put quotes (") around it. The third argument can be used to specify the width or height of the image. This is only useful for \f$\mbox{\LaTeX}\f$ output @@ -1057,19 +1070,28 @@ Doxygen. Unrecognized commands are treated as normal text. size specifier in \f$\mbox{\LaTeX}\f$ (for example <code>10cm</code> or <code>6in</code>). + Here is example of a comment block: + \verbatim /*! Here is a snapshot of my new application: - * \image html ../images/application.jpg - * \image latex ../images/application.eps width=10cm + * \image html application.jpg + * \image latex application.eps width=10cm */ \endverbatim + And this is an example of how the configuration file may look: + +\verbatim + IMAGE_PATH = my_image_dir + IMAGE_PATTERNS = *.eps *.gif *.jpg +\endverbatim + \warning The image format for HTML is limited to what your browser supports. For \f$\mbox{\LaTeX}\f$ the image format must be an encapsulated postscipt (eps). <br><br> - Doxygen does not check if an image exists or if it is in - the correct format. So \e you have to make sure this is the case! + Doxygen does not check if the image is in the correct format. + So \e you have to make sure this is the case! <hr> \subsection cmdlatexonly \latexonly @@ -1084,7 +1106,7 @@ Doxygen. Unrecognized commands are treated as normal text. use the \\htmlonly and \\endhtmlonly pair to provide a proper HTML alternative. - \b Notice: + \b Note: environment variables (like \$(HOME) ) are resolved inside a \f$\mbox{\LaTeX}\f$-only block. @@ -1209,7 +1231,6 @@ browser generator. Do \e not use these commands in your own documentation. <li>\\functionindex <li>\\header <li>\\headerfilelist -<li>\\ingroup <li>\\inherit <li>\\l <li>\\postheader diff --git a/doc/config.doc b/doc/config.doc index 66eb694..f46964b 100644 --- a/doc/config.doc +++ b/doc/config.doc @@ -58,12 +58,14 @@ followed by the descriptions of the tags grouped by category. <li> \refitem cfg_cgi_name CGI_NAME <li> \refitem cfg_cgi_url CGI_URL <li> \refitem cfg_class_diagrams CLASS_DIAGRAMS +<li> \refitem cfg_cols_in_alpha_index COLS_IN_ALPHA_INDEX <li> \refitem cfg_compact_latex COMPACT_LATEX <li> \refitem cfg_disable_index DISABLE_INDEX <li> \refitem cfg_doc_abspath DOC_ABSPATH <li> \refitem cfg_doc_url DOC_URL <li> \refitem cfg_enable_preprocessing ENABLE_PREPROCESSING <li> \refitem cfg_example_path EXAMPLE_PATH +<li> \refitem cfg_example_patterns EXAMPLE_PATTERNS <li> \refitem cfg_exclude EXCLUDE <li> \refitem cfg_exclude_patterns EXCLUDE_PATTERNS <li> \refitem cfg_expand_only_predef EXPAND_ONLY_PREDEF @@ -84,6 +86,9 @@ followed by the descriptions of the tags grouped by category. <li> \refitem cfg_html_footer HTML_FOOTER <li> \refitem cfg_html_header HTML_HEADER <li> \refitem cfg_html_output HTML_OUTPUT +<li> \refitem cfg_html_stylesheet HTML_STYLESHEET +<li> \refitem cfg_image_path IMAGE_PATH +<li> \refitem cfg_image_patterns IMAGE_PATTERNS <li> \refitem cfg_include_path INCLUDE_PATH <li> \refitem cfg_inherit_docs INHERIT_DOCS <li> \refitem cfg_inline_info INLINE_INFO @@ -190,7 +195,8 @@ followed by the descriptions of the tags grouped by category. If the \c EXTRACT_ALL tag is set to \c YES all classes and functions will be included in the documentation, even if no documentation was available. - \b Notice: This will also disable the warnings about undocumented members + \par Note: + This will also disable the warnings about undocumented members that are normally produced when \c WARNINGS is set to \c YES \anchor cfg_extract_private @@ -238,7 +244,7 @@ followed by the descriptions of the tags grouped by category. prepend the brief description of a member or function before the detailed description - \par Notice: + \par Note: If both \c HIDE_UNDOC_MEMBERS and \c BRIEF_MEMBER_DESC are set to \c NO, the brief descriptions will be completely suppressed. @@ -290,7 +296,7 @@ followed by the descriptions of the tags grouped by category. \anchor cfg_javadoc_autobrief <dt>\c JAVADOC_AUTOBRIEF <dd> - \addinex JAVADOC_AUTOBRIEF + \addindex JAVADOC_AUTOBRIEF If the \c JAVADOC_NO_AUTOBRIEF is set to \c YES (the default) then Doxygen will interpret the first line (until the first dot) of a JavaDoc-style comment as the brief description. If set to NO, the Javadoc-style will @@ -304,7 +310,7 @@ followed by the descriptions of the tags grouped by category. reimplements. \anchor cfg_inline_info -<dt> INLINE_INFO <dd> +<dt>\c INLINE_INFO <dd> If the \c INLINE_INFO tag is set to \c YES (the default) then a tag [inline] is inserted in the documentation for inline members. @@ -321,7 +327,8 @@ followed by the descriptions of the tags grouped by category. \c myfile.cpp or directories like \c /usr/src/myproject. Separate the files or directories with spaces.<br> - \b Notice: This tag (and only this tag) is \e required. + \b Note: + This tag (and only this tag) is \e required. \anchor cfg_file_patterns <dt>\c FILE_PATTERNS <dd> @@ -360,6 +367,29 @@ followed by the descriptions of the tags grouped by category. directories that contain example code fragments that are included (see the \\include command in section \ref cmdinclude "\\include"). +\anchor cfg_example_patterns +<dt>\c EXAMPLE_PATTERNS <dd> + \addindex EXAMPLE_PATTERNS + If the value of the \c EXAMPLE_PATH tag contains directories, you can use the + \c EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp + and *.h) to filter out the source-files in the directories. If left + blank all files are included. + +\anchor cfg_image_path +<dt>\c IMAGE_PATH <dd> + \addindex IMAGE_PATH + The \c IMAGE_PATH tag can be used to specify one or more files or + directories that contain images that are to be included in the + documentation (see the \ref cmdimage "\image" command). + +\anchor cfg_image_patterns +<dt>\c IMAGE_PATTERNS <dd> + \addindex IMAGE_PATTERNS + If the value of the \c IMAGE_PATH tag contains directories, you can use the + \c IMAGE_PATTERNS tag to specify one or more wildcard pattern (like *.gif + and *.eps) to filter out the image files in the directories. If left + blank all files are included. + \anchor cfg_input_filter <dt>\c INPUT_FILTER <dd> \addindex INPUT_FILTER @@ -410,9 +440,11 @@ followed by the descriptions of the tags grouped by category. standard header. The following commands have a special meaning inside the header: - <code>\$title</code>, <code>\$datetime</code>, <code>\$date</code>. + <code>\$title</code>, <code>\$datetime</code>, <code>\$date</code>, + <code>\$doxygenversion</code>. Doxygen will replace them by respectively - the title of the page, the current date and time, or only the current date. + the title of the page, the current date and time, only the current date, + or the version number of doxygen. \anchor cfg_html_footer <dt>\c HTML_FOOTER <dd> @@ -431,6 +463,28 @@ followed by the descriptions of the tags grouped by category. Doxygen will replace them by respectively the title of the page, the current date and time, or only the current date. +\anchor cfg_html_stylesheet +<dt>\c HTML_STYLESHEET <dd> + \addindex HTML_STYLESHEET + The \c HTML_STYLESHEET tag can be used to specify a user defined cascading + style sheet that is used by each HTML page. It can be used to + fine-tune the look of the HTML output. If the tag is left blank doxygen + will generate a default style sheet. Here is the default style sheet + that doxygen normally generates: + +\verbatim +H1 { text-align: center } +A.el { text-decoration: none; font-weight: bold } +DL.el { margin-left: -1cm } +DIV.fragment { width: 100%; border: none; background-color: #eeeeee } +DIV.in { margin-left: 16 } +DIV.ah { background-color: black; margin-bottom: 3; margin-top: 3 } +A.gl:link { color: #ffffff } +A.gl:visited { color: #ffffff } +A.gl { text-decoration: none; font-weight: bold; background-color: #ff8080 } +TD.md { background-color: #f2f2ff } +\endverbatim + \anchor cfg_html_align_members <dt>\c HTML_ALIGN_MEMBERS <dd> @@ -438,14 +492,14 @@ If the \c HTML_ALIGN_MEMBERS tag is set to \c YES, the members of classes, files or namespaces will be aligned in HTML using tables. If set to NO a bullet list will be used. -\par Notice +<b>Note:</b> Setting this tag to NO will become obsolete in the future, since I only intent to support and test the aligned representation. \anchor cfg_generate_htmlhelp <dt>\c GENERATE_HTMLHELP <dd> -If the \c GENERATE_HTMLHELP tag is set to \c YES, +If the \c GENERATE_HTMLHELP tag is set to \c YES then doxygen generates three additional HTML index files: \c index.hhp, \c index.hhc, and \c index.hhk. The \c index.hhp is a project file that can be read by @@ -472,6 +526,13 @@ If the \c ALPHABETICAL_INDEX tag is set to \c YES, an alphabetical index of all compounds will be generated. Enable this if the project contains a lot of classes, structs, unions or interfaces. +\anchor cfg_cols_in_alpha_index +<dt>\c COLS_IN_ALPHA_INDEX <dd> + +If the alphabetical index is enabled +(see \c ALPHABETICAL_INDEX) then the \c COLS_IN_ALPHA_INDEX tag can be +used to specify the number of columns in which this list will be split (can be a number in the range [1..20]) + </dl> \subsection latex_output LaTeX related options @@ -515,7 +576,7 @@ a lot of classes, structs, unions or interfaces. \anchor cfg_extra_packages <dt>\c EXTRA_PACKAGES <dd> \addindex EXTRA_PACKAGES - The EXTRA_PACKAGES tag can be used to specify one or more \f$\mbox{\LaTeX}\f$ + The \c EXTRA_PACKAGES tag can be used to specify one or more \f$\mbox{\LaTeX}\f$ package names that should be included in the \f$\mbox{\LaTeX}\f$ output. To get the times font for instance you can specify \verbatim @@ -555,7 +616,7 @@ EXTRA_PACKAGES = times \pagenumbering{arabic} \endverbatim - \par Notice: + \par Note: Only use a user defined header if you know what you are doing! </dl> @@ -581,7 +642,7 @@ EXTRA_PACKAGES = times \anchor cfg_man_extension <dt>\c MAN_EXTENSION <dd> \addindex MAX_EXTENSION - The MAN_EXTENSION tag determines the extension that is added to + The \c MAN_EXTENSION tag determines the extension that is added to the generated man pages (default is the subroutine's section .3) </dl> @@ -643,7 +704,7 @@ EXTRA_PACKAGES = times See section \ref doxytag_usage for more information about the usage of tag files. - \par Notice: + \par Note: Each tag file most have a unique name and if a tag file is not located in the directory in which doxygen is run, you must also specify the path to the tagfile here. diff --git a/doc/doxygen_usage.doc b/doc/doxygen_usage.doc index b9f98b3..ff6f117 100644 --- a/doc/doxygen_usage.doc +++ b/doc/doxygen_usage.doc @@ -41,9 +41,15 @@ doxygen <config_file> \endverbatim </ol> -The \c -s option is optional and can be used suppress the description that -doxygen normally generates for each tag. Try to use this option if you send -me configuration files! +<b>Note:</b><br> +<ul> +<li> If you do not want the description for each item in the configuration + file then you can use the optional \c -s option. + Try to use this option if you send me a configuration file as part of + a bug report! +<li> To make doxygen read/write to standard input/output instead of from/to + a file, use \c - for the file name. +</ul> If you also want to use the search engine, you should look at section \ref doxysearch_usage. diff --git a/doc/doxysearch_usage.doc b/doc/doxysearch_usage.doc index e3b1657..6024d2a 100644 --- a/doc/doxysearch_usage.doc +++ b/doc/doxysearch_usage.doc @@ -80,7 +80,7 @@ follow these steps: <li>\c search.gif: this is the image that is used for the search button. </ul> - \par Notice: + \par Note: On the Windows platform Unix shell scripts cannot be used. In fact the HTTP daemon that I tried (apache for Windows) only recognized <code>.cgi</code> files that were renamed @@ -106,9 +106,11 @@ follow these steps: <li>Run <a href="installdox_usage.html">installdox</a> to replace any dummy links in the documentation with real links. - <b>Notice:</b> When using a search engine this step is <em>required</em> + \par Note: + When using a search engine this step is <em>required</em> even if no tag files are used. If tag files are used you must specify the correct options. + </ol> <a name="searchqt"> @@ -128,7 +130,7 @@ This can be done by carefully following these steps: Apart from the file <code>search.idx</code> two other files will be generated: <code>search.gif</code> and <code>search.cgi</code> - \par Notice: + \par Note: Doxytag requires quite a large amount of memory to generate the search index (about 30 Mb on my Linux box)! The resulting index file requires about 3 Mb space on your disk. diff --git a/doc/doxytag_usage.doc b/doc/doxytag_usage.doc index fb966fd..cbccce8 100644 --- a/doc/doxytag_usage.doc +++ b/doc/doxytag_usage.doc @@ -28,7 +28,7 @@ It has two functions: documented in external documentation. Doxytag extracts this information directly from the HTML files. This has the advantage that you do not need to have the sources from which the documentation was extracted. - If you do have the sources you can also let \c doxygen generate the + If you \e do have the sources it is better to let \c doxygen generate the tag file by putting the name of the tag file after \c GENERATE_TAGFILE in the configuration file. <li> @@ -55,7 +55,7 @@ In both cases the input of doxytag consists of a set of HTML files. Then the documentation does not need to be regenerated by \c doxygen, only \c installdox has to be run. -\par Notice: +\par Note: Because the HTML files are expected to have a certain structure, only HTML files generated with doxygen or with Qt's class browser generator can be used. Doxytag only <em>reads</em> the HTML files, @@ -87,7 +87,7 @@ doxytag -t example.tag example/html installdox script that doxygen generates (See \ref installdox_usage for more information). - Notice that this is actually a feature because if you (or someone else) + Note that this is actually a feature because if you (or someone else) moves the external documentation to a different directory or URL you can simply run the script again and all links in the HTML files will be updated. @@ -109,7 +109,7 @@ A typical example to use doxytag to generate a search index is: doxytag -s search.idx \endverbatim -\par Notice: +\par Note: In the current version of doxygen, the search index must be called \c search.idx. diff --git a/doc/features.doc b/doc/features.doc index 7159124..aa3a33a 100644 --- a/doc/features.doc +++ b/doc/features.doc @@ -22,9 +22,13 @@ <li>Requires very little overhead from the writer of the documentation. Plain text will do, but for more fancy or structured output HTML tags and/or some of doxygen's special commands can be used. -<li>Outputs documentation in on-line format (HTML and man page) and off-line - format (LaTeX) simulatiously (any one can be disabled if desired). - Both formats are optimized for ease of reading. +<li>Outputs documentation in on-line format (HTML and UNIX man page) and + off-line format (\f$\mbox{\LaTeX}\f$) simultaniously + (any one can be disabled if desired). Both formats are optimized for + ease of reading. <br> + Furthermore, compressed HTML can be generated from HTML output using + Microsoft's HTML help workshop (Windows only) and PDF can be generated + from the \f$\mbox{\LaTeX}\f$ output. <li>Allows documentation of files, namespaces, classes, structs, unions, templates, variables, functions, typedefs, enums and defines. <li>Includes a full C preprocessor to allow proper parsing of conditional @@ -33,7 +37,7 @@ the Qt specific signal and slots sections. Extraction of private class members is optional. <li>Automatically generates of class diagrams in HTML (as clickable - image maps) and Latex (as encapsulated postscript). + image maps) and \f$\mbox{\LaTeX}\f$ (as encapsulated postscript images). <li>JavaDoc (1.1) and Qt-Doc compatible. <li>References to base/super classes and inherited/overridden members are generated automatically. @@ -46,7 +50,8 @@ of a member function or class. Most documentation systems (such as Javadoc) only support the former, others (such as Qt) only the latter. <li>You can type normal HTML tags in your documentation. Doxygen will convert - them to their equivalent Latex and man-page counterparts automatically. + them to their equivalent \f$\mbox{\LaTeX}\f$ and man-page + counterparts automatically. <li>Allows references to documentation generated for other projects (or another part of the same project) in a location independent way. <li>Allows inclusion of source code examples that are automatically @@ -54,12 +59,12 @@ <li>Inclusion of undocumented classes is also supported, allowing to quickly learn the structure and interfaces of a (large) piece of code without looking into the implementation details. -<li>All options are read from an easy to edit and documented configuration - file. +<li>Allows automatic cross-referencing of (documented) entities with their + definition in the source code. +<li>All options are read from an easy to edit and documented + configuration file. <li>Documentation and search engine can be transferred to another location or machine without regenerating the documentation. -<li>Doxygen can generate index and project files that can - be converted into compressed HTML by MicroSoft's HTML help workshop. <li>Can cope with large projects easily. </UL> diff --git a/doc/history.doc b/doc/history.doc index 3571bd6..ff29e7c 100644 --- a/doc/history.doc +++ b/doc/history.doc @@ -22,8 +22,6 @@ <li>Add support for grouping members, and document then as a group. <li>Support for K&R-style function arguments. <li>More ouput formats: suggested are info format and RTF format. -<li>Reintroduction of the multi-column class list (and file list) to quickly - select a class or file <li>Split long lists in an index to a set of smaller lists. <li>Add a nice graphical front-end for creating and modifying the configuration file (it should be flexible enough to quickly add new options). @@ -34,15 +32,18 @@ not yet listed here, please let me know. </ul> -<h3>Features scheduled for version 0.5</h3> +<h3>Features scheduled for version 1.0</h3> <ul> -<li>Proper support for namespaces. -<li>Include LaTeX style formulas in LaTeX and HTML output (in HTML as a gif). -<li>Proper support for template classes, members, functions and specializations. -<li>Multi-lingual support. -<li>Generation of class diagrams (clickable image maps in HTML, eps images in - postscript). -<li>Add generator for man pages format. + <li>Include LaTeX style formulas in LaTeX and HTML output (in HTML as a gif). + <li>Multi-lingual support: currently supported languages are: English, + Dutch, French, German, Italian, Swedish, Czech, Japanese. + <li>Generation of class diagrams (clickable image maps in HTML, eps images + in postscript). + <li>Output generator for the man page format. + <li>Proper support for template classes, members, functions and specializations. + <li>Proper support for namespaces. + <li>Reintroduction of the multi-column class list (and file list) to quickly + select a class or file </ul> <h3>Version 0.4</h3> diff --git a/doc/htmlcmds.doc b/doc/htmlcmds.doc index 7a35200..38b1459 100644 --- a/doc/htmlcmds.doc +++ b/doc/htmlcmds.doc @@ -16,7 +16,7 @@ /*! \page htmlcmds HTML Commands Here is a list of all HTML commands that may be used inside the -documentation. Notice that all attributes of a HTML tag are ignored +documentation. Note that all attributes of a HTML tag are ignored (the HREF and NAME attributes for the A tag are the only exception). <ul> diff --git a/doc/index.doc b/doc/index.doc index dc12600..5684f6c 100644 --- a/doc/index.doc +++ b/doc/index.doc @@ -180,8 +180,10 @@ Matthias Baas, Walter Mueller, William van Dieten, Joshua Jensen, -Patrick Aberts, +Patrick Alberts, Jacques Tremblay, +John Sturton, +Moshe Kruger, and many others for suggestions, patches and bug reports. </ul> */ diff --git a/doc/installdox_usage.doc b/doc/installdox_usage.doc index d22e4a7..11f8710 100644 --- a/doc/installdox_usage.doc +++ b/doc/installdox_usage.doc @@ -40,7 +40,7 @@ The following options are available: that is used by doxygen. The location <tt>\<location\></tt> can be an absolute path or a URL. - \par Notice: + \par Note: Each <tagfile> must be unique and should only be the name of the file, not including the path. diff --git a/doc/language.doc b/doc/language.doc index 2440a08..96afee0 100644 --- a/doc/language.doc +++ b/doc/language.doc @@ -35,7 +35,8 @@ Here is a list of the languages and their current maintainers: <TR BGCOLOR="#4040c0"> <TD ><b><font size=+1 color="#ffffff"> Language </font></b></TD> <TD ><b><font size=+1 color="#ffffff"> Maintainer </font></b></TD> - <TD ><b><font size=+1 color="#ffffff"> Contact address </font></b></TD> + <TD ><b><font size=+1 color="#ffffff"> Contact address </font> + <font size=-2 color="#ffffff">(remove the NOSPAM.)</font></b></TD> <TR BGCOLOR="#ffffff"> <TD> German @@ -44,8 +45,8 @@ Here is a list of the languages and their current maintainers: Jens Breitenstein </TD> <TD> - <a href="mailto:Jens.Breitenstein@tlc.de"> - Jens.Breitenstein@tlc.de</a> + <a href="mailto:Jens.Breitenstein@NOSPAM.tlc.de"> + Jens.Breitenstein@NOSPAM.tlc.de</a> </TD> </TR> <TR BGCOLOR="#ffffff"> @@ -56,8 +57,8 @@ Here is a list of the languages and their current maintainers: Christophe Bordeux </TD> <TD> - <a href="mailto:bordeux@lig.di.epfl.ch"> - bordeux@lig.di.epfl.ch</a> + <a href="mailto:bordeux@NOSPAM.lig.di.epfl.ch"> + bordeux@NOSPAM.lig.di.epfl.ch</a> </TD> </TR> <TR BGCOLOR="#ffffff"> @@ -69,10 +70,10 @@ Here is a list of the languages and their current maintainers: XeT Erixon </TD> <TD> - <a href="mailto:sahag96@nts.mh.se"> - sahag96@nts.mh.se</a><br> - <a href="mailto:xet@hem.passagen.se"> - xet@hem.passagen.se</a> + <a href="mailto:sahag96@NOSPAM.nts.mh.se"> + sahag96@NOSPAM.nts.mh.se</a><br> + <a href="mailto:xet@NOSPAM.hem.passagen.se"> + xet@NOSPAM.hem.passagen.se</a> </TD> </TR> <TR BGCOLOR="#ffffff"> @@ -83,8 +84,8 @@ Here is a list of the languages and their current maintainers: Vlastimil Havran </TD> <TD> - <a href="mailto:havran@fel.cvut.cz"> - havran@fel.cvut.cz</a> + <a href="mailto:havran@NOSPAM.fel.cvut.cz"> + havran@NOSPAM.fel.cvut.cz</a> </TD> </TR> <TR BGCOLOR="#ffffff"> @@ -95,8 +96,8 @@ Here is a list of the languages and their current maintainers: Ionutz Borcoman </TD> <TD> - <a href="mailto:borco@borco-ei.eng.hokudai.ac.jp"> - borco@borco-ei.eng.hokudai.ac.jp</a> + <a href="mailto:borco@NOSPAM.borco-ei.eng.hokudai.ac.jp"> + borco@NOSPAM.borco-ei.eng.hokudai.ac.jp</a> </TD> </TR> <TR BGCOLOR="#ffffff"> @@ -107,8 +108,8 @@ Here is a list of the languages and their current maintainers: Piotr Piatkowski </TD> <TD> - <a href="mailto:kompas@ceti.com.pl"> - kompas@ceti.com.pl</a> + <a href="mailto:kompas@NOSPAM.ceti.com.pl"> + kompas@NOSPAM.ceti.com.pl</a> </TD> </TR> <TR BGCOLOR="#ffffff"> @@ -120,10 +121,10 @@ Here is a list of the languages and their current maintainers: Alessandro Falappa </TD> <TD> - <a href="mailto:aaf23@cam.ac.uk"> - aaf23@cam.ac.uk</a><br> - <a href="mailto:a.falappa@flashnet.it"> - a.falappa@flashnet.it</a> + <a href="mailto:aaf23@NOSPAM.cam.ac.uk"> + aaf23@NOSPAM.cam.ac.uk</a><br> + <a href="mailto:a.falappa@NOSPAM.flashnet.it"> + a.falappa@NOSPAM.flashnet.it</a> </TD> </TR> <TR BGCOLOR="#ffffff"> @@ -134,8 +135,8 @@ Here is a list of the languages and their current maintainers: Kenji Nagamatsu </TD> <TD> - <a href="mailto:naga@joyful.club.ne.jp"> - naga@joyful.club.ne.jp</a> + <a href="mailto:naga@NOSPAM.joyful.club.ne.jp"> + naga@NOSPAM.joyful.club.ne.jp</a> </TD> </TR> <TR BGCOLOR="#ffffff"> @@ -146,8 +147,8 @@ Here is a list of the languages and their current maintainers: Francisco Oltra Thennet </TD> <TD> - <a href="mailto:foltra@puc.cl"> - foltra@puc.cl</a> + <a href="mailto:foltra@NOSPAM.puc.cl"> + foltra@NOSPAM.puc.cl</a> </TD> </TR> <TR BGCOLOR="#ffffff"> @@ -158,8 +159,8 @@ Here is a list of the languages and their current maintainers: Olli Korhonen </TD> <TD> - <a href="mailto:Olli.Korhonen@ccc.fi"> - Olli.Korhonen@ccc.fi</a> + <a href="mailto:Olli.Korhonen@NOSPAM.ccc.fi"> + Olli.Korhonen@NOSPAM.ccc.fi</a> </TD> </TR> <TR BGCOLOR="#ffffff"> @@ -170,8 +171,8 @@ Here is a list of the languages and their current maintainers: Vladimir Vodolazkiy </TD> <TD> - <a href="mailto:voldemarus@geocities.com"> - voldemarus@geocities.com</a> + <a href="mailto:voldemarus@NOSPAM.geocities.com"> + voldemarus@NOSPAM.geocities.com</a> </TD> </TR> @@ -183,8 +184,8 @@ Here is a list of the languages and their current maintainers: Dimitri van Heesch </TD> <TD> - <a href="mailto:dimitri@stack.nl"> - dimitri@stack.nl</a> + <a href="mailto:dimitri@NOSPAM.stack.nl"> + dimitri@NOSPAM.stack.nl</a> </TD> </TR> </TABLE> @@ -201,7 +202,7 @@ Here is a list of the languages and their current maintainers: \hline French & Christophe Bordeux & {\tt bordeux@lig.di.epfl.ch} \\ \hline - Swedish & Samuel Hägglund & {\tt sahag96@nts.mh.se} \\ + Swedish & Samuel H\"agglund & {\tt sahag96@nts.mh.se} \\ & XeT Erixon & {\tt xet@hem.passagen.se} \\ \hline Czech & Vlastimil Havran & {\tt havran@fel.cvut.cz} \\ diff --git a/doc/starting.doc b/doc/starting.doc index e89f717..293f6b2 100644 --- a/doc/starting.doc +++ b/doc/starting.doc @@ -20,7 +20,7 @@ generates the documentation. See section \ref doxygen_usage for more detailed usage information. The executable \c doxytag is only needed if you want to generate references -to external documentation (i.e. documentation that was generated by Doxygen) +to external documentation (i.e. documentation that was generated by doxygen) for which you do not have the sources or to create a search index for the search engine. See section \ref doxytag_usage for more detailed usage information. @@ -35,7 +35,7 @@ Each project should get its own configuration file. A project can consist of a single source file, but can also be an entire source tree that is recursively scanned. -To simplify the creation of a configuration file, Doxygen can create a +To simplify the creation of a configuration file, doxygen can create a template configuration file for you. To do this call \c doxygen with the \c -g option: @@ -44,8 +44,10 @@ doxygen -g <config-file> \endverbatim where \<config-file\> is the name of the configuration file. If you omit the file name, a file named \c Doxyfile will be created. If a file with the -name \<config-file\> already exists, Doxygen will rename it to +name \<config-file\> already exists, doxygen will rename it to \<config-file\>.bak before generating the configuration template. +If you use <code>-</code> as the file name then doxygen will try to read +the configuration file from standard input (<code>stdin</code>). The configuration file has a format that is similar to that of a (simple) Makefile. It contains of a number of assignments (tags) of the form: @@ -53,7 +55,8 @@ Makefile. It contains of a number of assignments (tags) of the form: <tt>TAGNAME = VALUE</tt> or <br> <tt>TAGNAME = VALUE1 VALUE2 ... </tt><br> -You can probably leave the values of most tags to their default value. +You can probably leave the values of most tags in a generated template +configuration file to their default value. The \c INPUT tag is the only tag for which you are required to provide a value. See section \ref config for more details about the configuration file. @@ -62,20 +65,25 @@ you can add the names of the files after the \c INPUT tag. If you have a larger project consisting of a source directory or tree this may become tiresome. In this case you should put the root directory or directories after the \c INPUT tag, and add one or more file -patterns to the \c FILE_PATTERN tag. Only files that match one of the +patterns to the \c FILE_PATTERN tag (for instance <code>*.cpp *.h</code>). +Only files that match one of the patterns will be parsed (if the patterns are omitted all files will be parsed). For recursive parsing of a source tree you must set -the \c RECURSIVE tag to \c YES. To further finetune the list of files +the \c RECURSIVE tag to \c YES. To further fine-tune the list of files that is parsed the \c EXCLUDE and \c EXCLUDE_PATTERNS tags can be used. -If you start using Doxygen for an existing project (thus without any -documentation that Doxygen is aware of), you can still get an idea of +If you start using doxygen for an existing project (thus without any +documentation that doxygen is aware of), you can still get an idea of what the documented result would be. To do so, you must set the \c EXTRACT_ALL -tag in the configuration file to \c YES. Then, Doxygen will pretend +tag in the configuration file to \c YES. Then, doxygen will pretend everything in your sources is documented. Please note that warnings of undocumented members will not be generated as long as \c EXTRACT_ALL is set to \c YES. +To analyse an existing piece of software it is useful to cross-reference +a (documented) entity with its definition in the source files. Doxygen will +generate such cross-references if you set the SOURCE_BROWSER tag to YES. + \subsection step2 Step 2: Running doxygen To generate the documentation you can now enter: @@ -100,24 +108,28 @@ exist, \c doxygen will try to create it for you. The generated HTML documentation can be viewed by pointing a HTML browser to the \c index.html file in the \c html directory. For the best results a browser that supports cascading style sheets (CSS) should be used -(I'm currently using Netscape 4.0 to test the generated output). +(I'm currently using Netscape 4.61 to test the generated output). \addindex LaTeX The generated \f$\mbox{\LaTeX}\f$ documentation must first be compiled by -a \f$\mbox{\LaTeX}\f$ compiler. (I use teTeX distribution version 0.4 +a \f$\mbox{\LaTeX}\f$ compiler. (I use teTeX distribution version 0.9 that contains \f$\mbox{\TeX}\f$ version 3.14159). To simplify the process of compiling the generated documentation, \c doxygen writes a \c Makefile into the \c latex directory. By typing \c make in the \c latex directory the dvi file \c refman.dvi -will be generated. This file can then be viewed using \c xdvi or +will be generated (provided that you have a make tool called +<code>make</code> ofcourse). This file can then be viewed using \c xdvi or converted into a postscript file \c refman.ps by typing <code>make ps</code> -(this requires \c dvips ). The Postscript file can be send to a postscript +(this requires \c dvips ). Conversion to PDF is also possible; just type +<code>make pdf</code>. The Postscript file can be send to a postscript printer. If you do not have a postscript printer, you can try to use ghostscript to convert postscript into something your printer understands. +To get the best results for PDF output you should set the +\c PDF_HYPERLINKS tag to \c YES. The generated man pages can be viewed using the \c man program. You do need -to make sure the man directory is in the man path (see the MANPATH -environment variable). Notice that there are some limitations to the +to make sure the man directory is in the man path (see the \c MANPATH +environment variable). Note that there are some limitations to the capabilities of the man page format, so some information (like class diagrams, cross references and formulas) will be lost. @@ -125,7 +137,7 @@ capabilities of the man page format, so some information Although documenting the source is presented as step 3, in a new project this should ofcourse be step 1. Here I assume -you already have some code and you want Doxygen to generate a nice document +you already have some code and you want doxygen to generate a nice document describing the API and maybe the internals as well. If the \c EXTRACT_ALL option is set to \c NO in the configuration file @@ -141,7 +153,7 @@ these? For members, classes and namespaces there are basicly two options: <li>Place a special documentation block somewhere else (another file or another location) \e and put a <em>structural command</em> in the documentation block. A structural command links a documentation block - to a certain object that can be documented (e.g. a member, class, + to a certain entity that can be documented (e.g. a member, class, namespace or file). See section \ref structuralcommands to learn more about structural commands. </ol> @@ -170,7 +182,7 @@ During parsing the following steps take place: \subsection specialblock Special documentation blocks -The following types of special documentation blocks are supported by Doxygen: +The following types of special documentation blocks are supported by doxygen: <ul> <li>The Qt style, where special documentation blocks look like: \verbatim @@ -196,14 +208,14 @@ Here is an example of a documented piece of C++ code using the Qt style: \verbinclude qtstyle.cpp \htmlonly Click <a href="$(DOXYGEN_DOCDIR)/examples/qtstyle/html/class_test.html">here</a> - for the corresponding HTML documentation that is generated by Doxygen. + for the corresponding HTML documentation that is generated by doxygen. \endhtmlonly The one-line comments should contain a brief description, whereas the multi-line comment blocks contain a more detailed description. The brief descriptions are included in the member overview of a class, namespace or file and are printed using a small italic font -(this description can be omitted by setting \c BRIEF_STDMETHOD_DESC to \c NO in +(this description can be omitted by setting \c BRIEF_MEMBER_DESC to \c NO in the config file). By default the brief descriptions are also the first sentence of the detailed description (this can be changed by setting the \c REPEAT_BRIEF tag to \c NO). @@ -215,15 +227,15 @@ style: \verbinclude jdstyle.cpp \htmlonly Click <a href="$(DOXYGEN_DOCDIR)/examples/jdstyle/html/class_test.html">here</a> - for the corresponding HTML documentation that is generated by Doxygen. + for the corresponding HTML documentation that is generated by doxygen. \endhtmlonly -Notice that the first sentence of the documentation (until the <tt>.</tt>) +Note that the first sentence of the documentation (until the <tt>.</tt>) is treated as a brief description, whereas the documentation block as a whole forms the detailed description. The brief description is required for the JavaDoc style. -Unlike most other documentation systems, Doxygen also allows you to put +Unlike most other documentation systems, doxygen also allows you to put the documentation of members (including global functions) in front of the \e definition. This way the documentation can be placed in the source file instead of the header file. This keeps the header file compact, and allows the @@ -248,7 +260,7 @@ Structural commands (like all other commands) start with a backslash (<tt>\\</tt>) followed by a command name and one or more parameters. For instance, if you want to document the class \c Test in the example above, you could have also put the following documentation block somewhere -in the input that is read by Doxygen: +in the input that is read by doxygen: \verbatim /*! \class Test \brief A test class. @@ -271,7 +283,7 @@ Other structural commands are: <li>\c \namespace to document a namespace. </ul> See section \ref commands for detailed information about these and other -commands. Notice that the documentation block belonging to a file +commands. Note that the documentation block belonging to a file should always contain a structural command. To document a member of a C++ class, you must also document the class @@ -285,10 +297,10 @@ using structural commands: \verbinclude structcmd.h \htmlonly Click <a href="$(DOXYGEN_DOCDIR)/examples/structcmd/html/structcmd.h.html">here</a> - for the corresponding HTML documentation that is generated by Doxygen. + for the corresponding HTML documentation that is generated by doxygen. \endhtmlonly -\par Notice: +\par Note: Because each comment block in the example above contains a structural command, all the comment blocks could be moved to another location or input file (the source file for instance), without affecting the generated @@ -300,7 +312,7 @@ using structural commands: If you want to document the members of a file, struct, union, class, or enum and you want to put the documentation for these members inside the compound, it is sometimes desired to place the documentation block after the member -instead of before. For this purpose Doxygen has the following +instead of before. For this purpose doxygen has the following additional comment blocks: \verbatim /*!< ... */ @@ -318,7 +330,7 @@ and \verbatim ///< ... \endverbatim -Notice that these blocks have the same structure and meaning as the +Note that these blocks have the same structure and meaning as the special comment blocks above only the \< indicates that the member is located in front of the block instead of after the block. @@ -326,7 +338,7 @@ Here is an example of a the use of these comment blocks: \verbinclude afterdoc.h \htmlonly Click <a href="$(DOXYGEN_DOCDIR)/examples/afterdoc/html/class_test.html">here</a> - for the corresponding HTML documentation that is generated by Doxygen. + for the corresponding HTML documentation that is generated by doxygen. \endhtmlonly \warning These blocks can only be used to document \e members. @@ -343,11 +355,11 @@ in the HTML documentation, you will also need to have the following tools installed <ul> <li>\c latex: the \f$\mbox{\LaTeX}\f$ compiler, needed to parse the formulas. - To test I have used the teTeX 0.4 distribution. + To test I have used the teTeX 0.9 distribution. <li>\c dvips: a tool to convert dvi files to postscript files - I have used version 5.58f from Radical Eye software for testing. + I have used version 5.86 from Radical Eye software for testing. <li>\c gs: the ghostscript interpreter for converting postscript files - to bitmaps. I have used Aladdin Ghostscript 5.01 for testing. + to bitmaps. I have used Aladdin Ghostscript 5.10 for testing. </ul> There are two ways to include formulas in the documentation. @@ -392,7 +404,7 @@ There are two ways to include formulas in the documentation. </ol> Formulas should be valid commands in \f$\mbox{\LaTeX}\f$'s math-mode. -\warning Currently, Doxygen is not very fault tolerant in recovering +\warning Currently, doxygen is not very fault tolerant in recovering from typos in formulas. It may have to be necessary to remove the file <code>formula.repository</code> that is written in the html directory to a rid of an incorrect formula @@ -442,7 +454,7 @@ after preprocessing becomes: static const char * version = "1.xx"; \endverbatim -Notice that doxygen will now expand \e all macro definitions +Note that doxygen will now expand \e 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 the \c EXPAND_ONLY_PREDEF tag to \c YES @@ -500,11 +512,11 @@ class IUnknown }; \endverbatim -Notice that the \c PREDEFINED tag accepts function like macro definitions +Note that the \c PREDEFINED tag accepts function like macro definitions (like \c DECLARE_INTERFACE), normal macro substitutions (like \c PURE and \c THIS) and plain defines (like \c __cplusplus). -Notice also that preprocessor definitions that are normally defined +Note also that preprocessor definitions that are normally defined automatically by the preprocessor (like \c __cplusplus), have to be defined by hand with doxygen's parser (this is done because these defines are often platform/compiler specific). diff --git a/doc/trouble.doc b/doc/trouble.doc index f02914b..a9aaf99 100644 --- a/doc/trouble.doc +++ b/doc/trouble.doc @@ -24,8 +24,8 @@ properly. If you find such a piece, please send it to me, so I can improve doxygen's parsing capabilities. Try to make the piece of code you send as small as possible, to help me narrow down the search. -<li>Using declarations and directives are not yet. They are - simply ignored. +<li>Using declarations are not yet supported. They are simply ignored. + Using directives are supported however. <li>Doxygen does not work properly if there are multiple classes, structs or unions with the same name in your code. It should not crash however, rather it should ignore all of the classes with the same name except one. @@ -42,7 +42,8 @@ \verbatim const int (a); \endverbatim - is also seen as a function declaration, because only the syntax is analysed, + is also seen as a function declaration with name + <code>int</code>, because only the syntax is analysed, not the semantics. If the redundant braces can be detected, as in \verbatim int *(a[20]); |