diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Doxyfile | 16 | ||||
| -rw-r--r-- | doc/Makefile.in | 12 | ||||
| -rw-r--r-- | doc/Makefile.latex | 18 | ||||
| -rw-r--r-- | doc/Makefile.win.in | 13 | ||||
| -rw-r--r-- | doc/commands.doc | 124 | ||||
| -rw-r--r-- | doc/config.doc | 215 | ||||
| -rw-r--r-- | doc/doxygen.sty | 13 | ||||
| -rw-r--r-- | doc/doxygen_manual.tex | 22 | ||||
| -rw-r--r-- | doc/doxygen_usage.doc | 6 | ||||
| -rw-r--r-- | doc/faq.doc | 20 | ||||
| -rw-r--r-- | doc/index.doc | 7 | ||||
| -rw-r--r-- | doc/language.doc | 29 | ||||
| -rw-r--r-- | doc/output.doc | 48 | ||||
| -rw-r--r-- | doc/starting.doc | 12 | ||||
| -rw-r--r-- | doc/trouble.doc | 4 |
15 files changed, 522 insertions, 37 deletions
diff --git a/doc/Doxyfile b/doc/Doxyfile index 859702b..c7f9138 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -1,3 +1,16 @@ +# +# $Id$ +# +# Copyright (C) 1997-1999 by Dimitri van Heesch. +# +# Permission to use, copy, modify, and distribute this software and its +# documentation under the terms of the GNU General Public License is hereby +# granted. No representations are made about the suitability of this software +# for any purpose. It is provided "as is" without express or implied warranty. +# See the GNU General Public License for more details. +# +# All output generated with Doxygen is not covered by this license. + PROJECT_NAME = OUTPUT_DIRECTORY = .. HTML_HEADER = @@ -14,7 +27,7 @@ ENABLE_PREPROCESSING = NO 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 autolink.doc \ + installdox_usage.doc output.doc autolink.doc \ config.doc commands.doc htmlcmds.doc language.doc FILE_PATTERNS = *.cpp *.h *.doc EXAMPLE_PATH = ../examples @@ -29,3 +42,4 @@ DOC_URL = DOC_ABSPATH = BIN_ABSPATH = /usr/local/bin/ EXT_DOC_PATHS = +PDF_HYPERLINKS = YES diff --git a/doc/Makefile.in b/doc/Makefile.in index 3b2d01c..29a3151 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -1,3 +1,15 @@ +# +# $Id$ +# +# Copyright (C) 1997-1999 by Dimitri van Heesch. +# +# Permission to use, copy, modify, and distribute this software and its +# documentation under the terms of the GNU General Public License is hereby +# granted. No representations are made about the suitability of this software +# for any purpose. It is provided "as is" without express or implied warranty. +# See the GNU General Public License for more details. +# +# All output generated with Doxygen is not covered by this license. all: FORCE DOXYGEN_DOCDIR=$(DOXYDOCS); \ diff --git a/doc/Makefile.latex b/doc/Makefile.latex index 7ab03a3..bd902df 100644 --- a/doc/Makefile.latex +++ b/doc/Makefile.latex @@ -1,4 +1,20 @@ -all: doxygen_manual.ps +# +# $Id$ +# +# Copyright (C) 1997-1999 by Dimitri van Heesch. +# +# Permission to use, copy, modify, and distribute this software and its +# documentation under the terms of the GNU General Public License is hereby +# granted. No representations are made about the suitability of this software +# for any purpose. It is provided "as is" without express or implied warranty. +# See the GNU General Public License for more details. +# +# All output generated with Doxygen is not covered by this license. + +all: doxygen_manual.pdf + +doxygen_manual.pdf: doxygen_manual.ps + ps2pdf doxygen_manual.ps doxygen_manual.pdf doxygen_manual.ps: doxygen_manual.dvi dvips -o doxygen_manual.ps doxygen_manual.dvi diff --git a/doc/Makefile.win.in b/doc/Makefile.win.in index e870a81..ed64837 100644 --- a/doc/Makefile.win.in +++ b/doc/Makefile.win.in @@ -1,3 +1,16 @@ +# +# $Id$ +# +# Copyright (C) 1997-1999 by Dimitri van Heesch. +# +# Permission to use, copy, modify, and distribute this software and its +# documentation under the terms of the GNU General Public License is hereby +# granted. No representations are made about the suitability of this software +# for any purpose. It is provided "as is" without express or implied warranty. +# See the GNU General Public License for more details. +# +# All output generated with Doxygen is not covered by this license. + all: FORCE set DOXYGEN_DOCDIR=file:///$(DOXYGEN) set VERSION=$(VERSION) diff --git a/doc/commands.doc b/doc/commands.doc index 5965aaf..d391c2c 100644 --- a/doc/commands.doc +++ b/doc/commands.doc @@ -70,12 +70,14 @@ documentation: <li> \refitem cmdfile \file <li> \refitem cmdfn \fn <li> \refitem cmdhtmlonly \htmlonly +<li> \refitem cmdimage \image <li> \refitem cmdinclude \include <li> \refitem cmdingroup \ingroup <li> \refitem cmdinternal \internal <li> \refitem cmdlatexonly \latexonly <li> \refitem cmdline \line <li> \refitem cmdlink \link +<li> \refitem cmdmainpage \mainpage <li> \refitem cmdnamespace \namespace <li> \refitem cmdoverload \overload <li> \refitem cmdpage \page @@ -84,6 +86,7 @@ documentation: <li> \refitem cmdref \ref <li> \refitem cmdrelates \relates <li> \refitem cmdreturn \return +<li> \refitem cmdretval \retval <li> \refitem cmdsa \sa <li> \refitem cmdsection \section <li> \refitem cmdskip \skip @@ -287,6 +290,38 @@ Doxygen. Unrecognized commands are treated as normal text. All text after a \c \internal command is ignored. <hr> +\subsection cmdmainpage \mainpage [(title)] + + \addindex \mainpage + + If the \\mainpage command is placed in a comment block the + block is used to customize the index page (in HTML) or + the first chapter (in \f$\mbox{\LaTeX}\f$). + + The title argument is optional and replaces the default title that + doxygen normally generates. + + Here is an example: +\verbatim +/*! \mainpage My Personal Index Page + * + * \section intro Introduction + * + * This is the introduction. + * + * \section install Installation + * + * \subsection step1 Step 1: Opening the box + * + * etc... + */ +\endverbatim + + \sa section \ref cmdsection "\\section", + section \ref cmdsubsection "\\subsection" and + section \ref cmdpage "\\page". + +<hr> \subsection cmdnamespace \namespace <name> \addindex \namespace @@ -338,6 +373,15 @@ Doxygen. Unrecognized commands are treated as normal text. Click <a href="$(DOXYGEN_DOCDIR)/examples/page/html/pages.html">here</a> for the corresponding HTML documentation that is generated by Doxygen. \endhtmlonly + + \par notice: + 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 + should set \c CASE_SENSE_NAMES to \c YES. However, this is advisable + only if your file system is case sensitive. Otherwise (and for better + portability) you should use all lower case letters (e.g. \c mypage1) + for \<name\> in all references to the page. \sa section \ref cmdsection "\\section", section \ref cmdsubsection "\\subsection", and section @@ -543,6 +587,23 @@ Doxygen. Unrecognized commands are treated as normal text. \sa Section \ref cmdjdreturn "@return". + +<hr> +\subsection cmdretval \retval <return value> { description } + + \addindex \retval + Starts a return value for a function with name + \<return value\>. Followed by a description of the return value. + The text of the paragraph that forms the description has no special + internal structure. All visual enhancement commands may be used inside the + paragraph. + Multiple adjacent \\retval commands will be joined into a single paragraph. + Each return value description will start on a new line. + The \\retval description ends when a blank line or some other + sectioning command is encountered. + + \sa Section \ref cmdjdretval "@retval". + <hr> \subsection cmdsa \sa { references } @@ -690,11 +751,17 @@ Doxygen. Unrecognized commands are treated as normal text. \addindex \dontinclude This command can be used to parse a source file without actually - including it. Any class and member declarations inside the code + verbatim including it in the documentation (as the \\include command does). + This is useful if you want to divide the source file into smaller pieces and + add documentation between the pieces. + Source files or directories can be specified using the \c EXAMPLE_PATH tag + of Doxygen's configuration file. + + The class and member declarations and definitions inside the code fragment are `remembered' during the parsing of the comment block that contained the \\dontinclude command. - For line by line description of source files, one or more lines + For line by line descriptions of source files, one or more lines of the example can be displayed using the \\line, \\skip, \\skipline, and \\until commands. An internal pointer is used for these commands. The \\dontinclude command sets the pointer to the first line of the example. @@ -717,8 +784,8 @@ Doxygen. Unrecognized commands are treated as normal text. \addindex \include This command can be used to include a source file as a block of code. The command takes the name of an include file as an argument. - Include files or directories can be specified using the - \c INCLUDE_PATH tag of Doxygen's configuration file. + Source files or directories can be specified using the + \c EXAMPLE_PATH tag of Doxygen's configuration file. Using the \\include command is equivalent to inserting the file into the documentation block and surrounding it @@ -728,10 +795,9 @@ Doxygen. Unrecognized commands are treated as normal text. duplication in case of example blocks that consist of multiple source and header files. - For line by line description of source files, one or more lines - of the example can be displayed using the \\line, \\skip, \\skipline, and - \\until commands. An internal pointer is used for these command. The - \\include command sets the pointer to the first line of the example. + For a line by line description of a source files use the + \\dontinclude command in combination with the \\line, \\skip, \\skipline, + and \\until commands. \sa section \ref cmdexample "\\example" and \ref cmddontinclude "\\dontinclude". @@ -967,6 +1033,45 @@ Doxygen. Unrecognized commands are treated as normal text. \ref cmdlatexonly "\\latexonly". <hr> +\subsection cmdimage \image <format> <file> [<sizeindication>=<size>] + + \addindex \image + Inserts an image into the documentation. This command is format + specific, so if you want to insert an image for more than one + format you'll have to repeat this command for each format. + + 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 third argument can be used to specify the width or height of the + image. This is only useful for \f$\mbox{\LaTeX}\f$ output + (i.e. format=latex). \c sizeindication can be either + \c width or \c height. The size should be a valid + size specifier in \f$\mbox{\LaTeX}\f$ (for example <code>10cm</code> or + <code>6in</code>). + +\verbatim + /*! Here is a snapshot of my new application: + * \image html ../images/application.jpg + * \image latex ../images/application.eps width=10cm + */ +\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! + +<hr> \subsection cmdlatexonly \latexonly \addindex \latexonly @@ -1078,6 +1183,9 @@ The following command JavaDoc command are support. \subsection cmdjdreturn @return { description of the return value } \addindex @return Equivalent to \\return (see section \ref cmdreturn "\\return"). +\subsection cmdjdretval @retval <return value name> { return value description } + \addindex @retval + Equivalent to \\retval (see section \ref cmdretval "\\retval"). \subsection cmdjdsee @see { references } \addindex @see Equivalent to \\sa (see section \ref cmdsa "\\sa"). diff --git a/doc/config.doc b/doc/config.doc index f238ad1..66eb694 100644 --- a/doc/config.doc +++ b/doc/config.doc @@ -25,7 +25,7 @@ recursive-descent parser that is built into \c doxygen. The file may contain tabs and newlines for formatting purposes. The statements in the file are case-sensitive. Comments may be placed anywhere within the file (except within quotes). -Comments begin with the \c # character and end at the end of the +Comments begin with the \# character and end at the end of the line. The file essentially consists of a list of assignment statements. @@ -38,11 +38,95 @@ as the last character of a line. Environment variables can expanded using the pattern \c $(ENV_VARIABLE_NAME). The configuration options can be divided into several categories. -Below is a list of tags that are recognized for each category. +Below is an alphabetical index of the tags that are recognized +followed by the descriptions of the tags grouped by category. + +\htmlonly +<multicol cols=3> +<ul> +\endhtmlonly +\latexonly +\footnotesize +\begin{multicols}{3} +\begin{CompactList} +\endlatexonly +<li> \refitem cfg_allexternals ALLEXTERNALS +<li> \refitem cfg_alphabetical_index ALPHABETICAL_INDEX +<li> \refitem cfg_bin_abspath BIN_ABSPATH +<li> \refitem cfg_brief_member_desc BRIEF_MEMBER_DESC +<li> \refitem cfg_case_sense_names CASE_SENSE_NAMES +<li> \refitem cfg_cgi_name CGI_NAME +<li> \refitem cfg_cgi_url CGI_URL +<li> \refitem cfg_class_diagrams CLASS_DIAGRAMS +<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_exclude EXCLUDE +<li> \refitem cfg_exclude_patterns EXCLUDE_PATTERNS +<li> \refitem cfg_expand_only_predef EXPAND_ONLY_PREDEF +<li> \refitem cfg_ext_doc_paths EXT_DOC_PATHS +<li> \refitem cfg_extra_packages EXTRA_PACKAGES +<li> \refitem cfg_extract_all EXTRACT_ALL +<li> \refitem cfg_extract_private EXTRACT_PRIVATE +<li> \refitem cfg_file_patterns FILE_PATTERNS +<li> \refitem cfg_full_path_names FULL_PATH_NAMES +<li> \refitem cfg_generate_html GENERATE_HTML +<li> \refitem cfg_generate_htmlhelp GENERATE_HTMLHELP +<li> \refitem cfg_generate_latex GENERATE_LATEX +<li> \refitem cfg_generate_man GENERATE_MAN +<li> \refitem cfg_generate_tagfile GENERATE_TAGFILE +<li> \refitem cfg_hide_undoc_classes HIDE_UNDOC_CLASSES +<li> \refitem cfg_hide_undoc_members HIDE_UNDOC_MEMBERS +<li> \refitem cfg_html_align_members HTML_ALIGN_MEMBERS +<li> \refitem cfg_html_footer HTML_FOOTER +<li> \refitem cfg_html_header HTML_HEADER +<li> \refitem cfg_html_output HTML_OUTPUT +<li> \refitem cfg_include_path INCLUDE_PATH +<li> \refitem cfg_inherit_docs INHERIT_DOCS +<li> \refitem cfg_inline_info INLINE_INFO +<li> \refitem cfg_input INPUT +<li> \refitem cfg_input_filter INPUT_FILTER +<li> \refitem cfg_internal_docs INTERNAL_DOCS +<li> \refitem cfg_javadoc_autobrief JAVADOC_AUTOBRIEF +<li> \refitem cfg_latex_header LATEX_HEADER +<li> \refitem cfg_latex_output LATEX_OUTPUT +<li> \refitem cfg_macro_expansion MACRO_EXPANSION +<li> \refitem cfg_man_extension MAN_EXTENSION +<li> \refitem cfg_man_output MAN_OUTPUT +<li> \refitem cfg_output_directory OUTPUT_DIRECTORY +<li> \refitem cfg_output_language OUTPUT_LANGUAGE +<li> \refitem cfg_paper_type PAPER_TYPE +<li> \refitem cfg_perl_path PERL_PATH +<li> \refitem cfg_predefined PREDEFINED +<li> \refitem cfg_project_name PROJECT_NAME +<li> \refitem cfg_project_number PROJECT_NUMBER +<li> \refitem cfg_quiet QUIET +<li> \refitem cfg_recursive RECURSIVE +<li> \refitem cfg_repeat_brief REPEAT_BRIEF +<li> \refitem cfg_search_includes SEARCH_INCLUDES +<li> \refitem cfg_searchengine SEARCHENGINE +<li> \refitem cfg_source_browser SOURCE_BROWSER +<li> \refitem cfg_strip_from_path STRIP_FROM_PATH +<li> \refitem cfg_tagfiles TAGFILES +<li> \refitem cfg_verbatim_headers VERBATIM_HEADERS +<li> \refitem cfg_warnings WARNINGS +\htmlonly +</ul> +</multicol> +\endhtmlonly +\latexonly +\end{CompactList} +\end{multicols} +\normalsize +\endlatexonly \subsection config_general General options <dl> +\anchor cfg_project_name <dt>\c PROJECT_NAME <dd> \addindex PROJECT_NAME The \c PROJECT_NAME tag is a single word (or a sequence of words @@ -50,12 +134,14 @@ Below is a list of tags that are recognized for each category. documentation is generated. This name is used in the title of most generated pages and in a few other places. +\anchor cfg_project_number <dt>\c PROJECT_NUMBER <dd> \addindex PROJECT_NUMBER The \c PROJECT_NUMBER tag can be used to enter a project or revision number. This could be handy for archiving the generated documentation or if some version control system is used. +\anchor cfg_output_directory <dt>\c OUTPUT_DIRECTORY <dd> \addindex OUTPUT_DIRECTORY The \c OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) @@ -63,6 +149,7 @@ Below is a list of tags that are recognized for each category. If a relative path is entered, it will be relative to the location where doxygen was started. If left blank the current directory will be used. +\anchor cfg_output_language <dt>\c OUTPUT_LANGUAGE <dd> \addindex OUTPUT_LANGUAGE The \c OUTPUT_LANGUAGE tag is used to specify the language in which all @@ -71,6 +158,7 @@ Below is a list of tags that are recognized for each category. The default language is English, other supported languages are: Dutch, French, Italian, Czech, Swedish, German and Japanese. +\anchor cfg_quiet <dt>\c QUIET <dd> \addindex QUIET The \c QUIET tag can be used to turn on/off the messages that are generated @@ -78,6 +166,7 @@ Below is a list of tags that are recognized for each category. where \c YES implies that the messages are off. If left blank \c NO is used. +\anchor cfg_warnings <dt>\c WARNINGS <dd> \addindex WARNINGS The \c WARNINGS tag can be used to turn on/off the warning messages that are @@ -86,6 +175,7 @@ Below is a list of tags that are recognized for each category. \b Tip: Turn warnings on while writing the documentation. +\anchor cfg_disable_index <dt>\c DISABLE_INDEX <dd> \addindex DISABLE_INDEX If you want full control over the layout of the generated HTML pages it @@ -94,6 +184,7 @@ Below is a list of tags that are recognized for each category. top of each page. A value of NO (the default) enables the index and the value YES disables it. +\anchor cfg_extract_all <dt>\c EXTRACT_ALL <dd> \addindex EXTRACT_ALL If the \c EXTRACT_ALL tag is set to \c YES all classes and functions will be @@ -102,11 +193,13 @@ Below is a list of tags that are recognized for each category. \b Notice: 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 <dt>\c EXTRACT_PRIVATE <dd> \addindex EXTRACT_PRIVATE If the \c EXTRACT_PRIVATE tag is set to \c YES all documentation for private members will be extracted as well. +\anchor cfg_hide_undoc_members <dt>\c HIDE_UNDOC_MEMBERS <dd> \addindex HIDE_UNDOC_MEMBERS If the \c HIDE_UNDOC_MEMBERS tag is set to \c YES, Doxygen will hide all @@ -114,6 +207,7 @@ Below is a list of tags that are recognized for each category. If set to \c NO (the default) these members will be included in the various overviews, but no documentation section is generated. +\anchor cfg_hide_undoc_classes <dt>\c HIDE_UNDOC_CLASSES <dd> \addindex HIDE_UNDOC_CLASSES If the \c HIDE_UNDOC_CLASSESS tag is set to \c YES, Doxygen will hide all @@ -121,6 +215,7 @@ Below is a list of tags that are recognized for each category. If set to \c NO (the default) these classes will be included in the various overviews. +\anchor cfg_brief_member_desc <dt>\c BRIEF_MEMBER_DESC <dd> \addindex BRIEF_MEMBER_DESC If the \c BRIEF_MEMBER_DESC tag is set to \c YES (the default) Doxygen will @@ -128,6 +223,7 @@ Below is a list of tags that are recognized for each category. the file and class documentation (similar to JavaDoc). Set to NO to disable this. +\anchor cfg_internal_docs <dt>\c INTERNAL_DOCS <dd> \addindex INTERNAL_DOCS The \c INTERNAL_DOCS tag determines if documentation @@ -135,6 +231,7 @@ Below is a list of tags that are recognized for each category. to \c NO (the default) then the documentation will be excluded. Set it to \c YES to include the internal documentation. +\anchor cfg_repeat_brief <dt>\c REPEAT_BRIEF <dd> \addindex REPEAT_BRIEF If the \c REPEAT_BRIEF tag is set to \c YES (the default) Doxygen will @@ -145,12 +242,14 @@ Below is a list of tags that are recognized for each category. If both \c HIDE_UNDOC_MEMBERS and \c BRIEF_MEMBER_DESC are set to \c NO, the brief descriptions will be completely suppressed. +\anchor cfg_full_path_names <dt>\c FULL_PATH_NAMES <dd> \addindex FULL_PATH_NAMES If the \c FULL_PATH_NAMES tag is set to \c YES Doxygen will prepend the full path before files name in the file list and in the header files. If set to NO the shortest path that makes the file name unique will be used +\anchor cfg_strip_from_path <dt>\c STRIP_FROM_PATH <dd> \addindex STRIP_FROM_PATH If the \c FULL_PATH_NAMES tag is set to \c YES then the \c STRIP_FROM_PATH tag @@ -158,18 +257,21 @@ Below is a list of tags that are recognized for each category. only done if one of the specified strings matches the left-hand part of the path. +\anchor cfg_class_diagrams <dt>\c CLASS_DIAGRAMS <dd> \addindex CLASS_DIAGRAMS If the \c CLASS_DIAGRAMS tag is set to \c YES (the default) Doxygen will - generate a class diagram (in Html and LaTeX) for classes with base or + generate a class diagram (in Html and \f$\mbox{\LaTeX}\f$) for classes with base or super classes. Setting the tag to \c NO turns the diagrams off. +\anchor cfg_source_browser <dt>\c SOURCE_BROWSER <dd> \addindex SOURCE_BROWSER If the \c SOURCE_BROWSER tag is set to \c YES than the body of a member or function will be appended as a block of code to the documentation of. that member or function. +\anchor cfg_case_sense_names <dt>\c CASE_SENSE_NAMES <dd> \addindex CASE_SENSE_NAMES If the \c CASE_SENSE_NAMES tag is set to \c NO (the default) then Doxygen @@ -178,25 +280,40 @@ Below is a list of tags that are recognized for each category. classes or files whose names only differ in case and if your file system supports case sensitive file names. +\anchor cfg_verbatim_headers <dt>\c VERBATIM_HEADERS <dd> \addindex VERBATIM_HEADERS - If the VERBATIM_HEADERS tag is set the YES (the default) then Doxygen\n"; - will generate a verbatim copy of the header file for each class for\n"; - which an include is specified. Set to NO to disable this.\n"; + If the \c VERBATIM_HEADERS tag is set the \c YES (the default) then Doxygen + will generate a verbatim copy of the header file for each class for + which an include is specified. Set to NO to disable this. \sa Section \ref cmdclass "\\class". +\anchor cfg_javadoc_autobrief <dt>\c JAVADOC_AUTOBRIEF <dd> \addinex JAVADOC_AUTOBRIEF - If the JAVADOC_NO_AUTOBRIEF is set to YES (the default) then Doxygen + 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 behave just like the Qt-style comments. +\anchor cfg_inherit_docs +<dt>\c INHERIT_DOCS <dd> + \addindex INHERIT_DOCS + If the \c INHERIT_DOCS tag is set to \c YES (the default) then an undocumented + member inherits the documentation from any documented member that it + reimplements. + +\anchor cfg_inline_info +<dt> 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. + </dl> \subsection config_input Input related options <dl> +\anchor cfg_input <dt>\c INPUT <dd> \addindex INPUT The \c INPUT tag is used to specify the files and/or directories that contain @@ -206,6 +323,7 @@ Below is a list of tags that are recognized for each category. \b Notice: This tag (and only this tag) is \e required. +\anchor cfg_file_patterns <dt>\c FILE_PATTERNS <dd> \addindex FILE_PATTERNS If the value of the \c INPUT tag contains directories, you can use the @@ -214,31 +332,35 @@ Below is a list of tags that are recognized for each category. in the directories. If left blank all files are included (i.e. wildcard <tt>*</tt>). +\anchor cfg_recursive <dt>\c RECURSIVE <dd> \addindex RECURSIVE The \c RECURSIVE tag can be used to specify whether or not subdirectories should be searched for input files as well. Possible values are \c YES and \c NO. If left blank \c NO is used. +\anchor cfg_exclude <dt>\c EXCLUDE <dd> \addindex EXCLUDE The \c EXCLUDE tag can be used to specify files and/or directories that should excluded from the \c INPUT source files. This way you can easily exclude a subdirectory from a directory tree whose root is specified with the \c INPUT tag. +\anchor cfg_exclude_patterns <dt>\c EXCLUDE_PATTERNS <dd> \addindex EXCLUDE_PATTERNS If the value of the INPUT tag contains directories, you can use the \c EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude certain files from those directories. - +\anchor cfg_example_path <dt>\c EXAMPLE_PATH <dd> \addindex EXAMPLE_PATH The \c EXAMPLE_PATH tag can be used to specify one or more files or directories that contain example code fragments that are included (see the \\include command in section \ref cmdinclude "\\include"). +\anchor cfg_input_filter <dt>\c INPUT_FILTER <dd> \addindex INPUT_FILTER The \c INPUT_FILTER tag can be used to specify a program that doxygen should @@ -257,17 +379,20 @@ Below is a list of tags that are recognized for each category. \subsection html_output HTML related options <dl> +\anchor cfg_generate_html <dt>\c GENERATE_HTML <dd> \addindex GENERATE_HTML If the \c GENERATE_HTML tag is set to \c YES (the default) Doxygen will generate HTML output +\anchor cfg_html_output <dt>\c HTML_OUTPUT <dd> \addindex HTML_OUTPUT The \c HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a relative path is entered the value of \c OUTPUT_DIRECTORY will be put in front of it. If left blank `html' will be used as the default path. +\anchor cfg_html_header <dt>\c HTML_HEADER <dd> \addindex HTML_HEADER The \c HTML_HEADER tag can be used to specify a user defined HTML @@ -289,6 +414,7 @@ Below is a list of tags that are recognized for each 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_footer <dt>\c HTML_FOOTER <dd> \addindex HTML_FOOTER The \c HTML_FOOTER tag can be used to specify a user defined HTML footer for @@ -305,6 +431,7 @@ Below is a list of tags that are recognized for each 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_align_members <dt>\c HTML_ALIGN_MEMBERS <dd> If the \c HTML_ALIGN_MEMBERS tag is set to \c YES, the members of classes, @@ -315,6 +442,7 @@ NO a bullet list will be used. 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, @@ -337,6 +465,7 @@ and you can search for words in the documentation (which basically renders \c doxysearch obsolete on Windows). The HTML workshop also contains a viewer for compressed HTML files. +\anchor cfg_alphabetical_index <dt>\c ALPHABETICAL_INDEX <dd> If the \c ALPHABETICAL_INDEX tag is set to \c YES, an alphabetical index @@ -348,23 +477,28 @@ a lot of classes, structs, unions or interfaces. \subsection latex_output LaTeX related options <dl> +\anchor cfg_generate_latex <dt>\c GENERATE_LATEX <dd> \addindex GENERATE_LATEX If the \c GENERATE_LATEX tag is set to \c YES (the default) Doxygen will generate Latex output. +\anchor cfg_latex_output <dt>\c LATEX_OUTPUT <dd> \addindex LATEX_OUTPUT - The \c LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. + The \c LATEX_OUTPUT tag is used to specify where the \f$\mbox{\LaTeX}\f$ + docs will be put. If a relative path is entered the value of \c OUTPUT_DIRECTORY will be put in front of it. If left blank `latex' will be used as the default path. +\anchor cfg_compact_latex <dt>\c COMPACT_LATEX <dd> \addindex COMPACT_LATEX If the \c COMPACT_LATEX tag is set to \c YES Doxygen generates more compact - LaTeX documents. This may be useful for small projects and may help to + \f$\mbox{\LaTeX}\f$ documents. This may be useful for small projects and may help to save some trees in general. +\anchor cfg_paper_type <dt>\c PAPER_TYPE <dd> \addindex PAPER_TYPE The PAPER_TYPE tag can be used to set the paper type that is used @@ -378,25 +512,64 @@ a lot of classes, structs, unions or interfaces. </ul> If left blank a4wide will be used. +\anchor cfg_extra_packages <dt>\c EXTRA_PACKAGES <dd> \addindex EXTRA_PACKAGES - The EXTRA_PACKAGES tag can be used to specify one or more LaTeX - package names that should be included in the LaTeX output. + The 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 EXTRA_PACKAGES = times \endverbatim If left blank no extra packages will be included. + +\anchor cfg_latex_header +<dt>\c LATEX_HEADER <dd> + \addindex LATEX_HEADER + The \c LATEX_HEADER tag can be used to specify a personal \f$\mbox{\LaTeX}\f$ + header for the generated latex document. The header should contain everything + until the first chapter. If it is left blank doxygen will generate a + standard header, which looks as follows for the default + configuration settings: + +\verbatim +\documentclass[a4paper]{book} +\usepackage{a4wide} +\usepackage{makeidx} +\usepackage{fancyheadings} +\usepackage{epsfig} +\usepackage{float} +\usepackage{doxygen} +\makeindex +\setcounter{tocdepth}{1} +\setlength{\footrulewidth}{0.4pt} +\begin{document} +\title{Reference Manual} +\author{Generated by Doxygen} +\date{Thu Sep 30 19:58:32 1999} +\maketitle +\pagenumbering{roman} +\clearemptydoublepage +\tableofcontents +\clearemptydoublepage +\pagenumbering{arabic} +\endverbatim + + \par Notice: + Only use a user defined header if you know what you are doing! + </dl> \subsection man_output Man page related options <dl> +\anchor cfg_generate_man <dt>\c GENERATE_MAN <dd> \addindex GENERATE_MAN If the \c GENERATE_MAN tag is set to \c YES (the default) Doxygen will generate man pages for classes and files. +\anchor cfg_man_output <dt>\c MAN_OUTPUT <dd> \addindex MAN_OUTPUT The \c MAN_OUTPUT tag is used to specify where the man pages will be put. @@ -405,6 +578,7 @@ EXTRA_PACKAGES = times A directory man3 will be created inside the directory specified by \c MAN_OUTPUT. +\anchor cfg_man_extension <dt>\c MAN_EXTENSION <dd> \addindex MAX_EXTENSION The MAN_EXTENSION tag determines the extension that is added to @@ -414,29 +588,34 @@ EXTRA_PACKAGES = times \subsection config_prepro Preprocessor related options <dl> +\anchor cfg_enable_preprocessing <dt>\c ENABLE_PREPROCESSING <dd> \addindex ENABLE_PREPROCESSING If the \c ENABLE_PREPROCESSING tag is set to \c YES (the default) Doxygen will evaluate all C-preprocessor directives found in the sources and include files. +\anchor cfg_macro_expansion <dt>\c MACRO_EXPANSION <dd> \addindex MACRO_EXPANSION If the \c MACRO_EXPANSION tag is set to \c YES Doxygen will expand all macro names in the source code. If set to \c NO (the default) only conditional compilation will be performed. +\anchor cfg_search_includes <dt>\c SEARCH_INCLUDES <dd> \addindex SEARCH_INCLUDES If the \c SEARCH_INCLUDES tag is set to \c YES (the default) the includes files in the \c INCLUDE_PATH (see below) will be search if a \#include is found. +\anchor cfg_include_path <dt>\c INCLUDE_PATH <dd> \addindex INCLUDE_PATH The \c INCLUDE_PATH tag can be used to specify one or more directories that contain include files that are not input files but should be processed by the preprocessor. +\anchor cfg_predefined <dt>\c PREDEFINED <dd> \addindex PREDEFINED The \c PREDEFINED tag can be used to specify one or more macro names that @@ -445,6 +624,7 @@ EXTRA_PACKAGES = times <code>name</code> or <code>name=definition</code> (no spaces). If the definition and the = are omitted =1 is assumed. +\anchor cfg_expand_only_predef <dt>\c EXPAND_ONLY_PREDEF <dd> \addindex EXPAND_ONLY_PREDEF If the \c EXPAND_ONLY_PREDEF and \c MACRO_EXPANSION tags are both set to YES @@ -456,6 +636,7 @@ EXTRA_PACKAGES = times \subsection config_extref External reference options <dl> +\anchor cfg_tagfiles <dt>\c TAGFILES <dd> \addindex TAGFILES The \c TAGFILES tag can be used to specify one or more tagfiles. @@ -467,6 +648,7 @@ EXTRA_PACKAGES = times in the directory in which doxygen is run, you must also specify the path to the tagfile here. +\anchor cfg_generate_tagfile <dt>\c GENERATE_TAGFILE <dd> \addindex GENERATE_TAGFILE When a file name is specified after \c GENERATE_TAGFILE, doxygen will create @@ -474,12 +656,14 @@ EXTRA_PACKAGES = times See section \ref doxytag_usage for more information about the usage of tag files. +\anchor cfg_allexternals <dt>\c ALLEXTERNALS <dd> \addindex ALLEXTERNALS if the \c ALLEXTERNALS tag is set to \c YES all external class will be listed in the class index. If set to \c NO only the inherited external classes will be listed. +\anchor cfg_perl_path <dt>\c PERL_PATH <dd> \addindex PERL_PATH The \c PERL_PATH should be the absolute path and name of the perl script @@ -489,6 +673,7 @@ EXTRA_PACKAGES = times \subsection config_search Search engine options <dl> +\anchor cfg_searchengine <dt>\c SEARCHENGINE <dd> \addindex SEARCHENGINE The \c SEARCHENGINE tag specifies whether or not a @@ -496,18 +681,21 @@ EXTRA_PACKAGES = times If set to \c NO or left blank, the values of all other tags in this section will be ignored. +\anchor cfg_cgi_name <dt>\c CGI_NAME <dd> \addindex CGI_NAME The \c CGI_NAME tag should be the name of the CGI script that starts the search engine (<tt>doxysearch</tt>) with the correct parameters. A script with this name will be generated by doxygen. +\anchor cfg_cgi_url <dt>\c CGI_URL <dd> \addindex CGI_URL The \c CGI_URL tag should be the absolute URL to the directory where the cgi binaries are located. See the documentation of your http daemon for details. +\anchor cfg_doc_url <dt>\c DOC_URL <dd> \addindex DOC_URL The \c DOC_URL tag should be the absolute URL to the directory where the @@ -515,17 +703,20 @@ EXTRA_PACKAGES = times documentation, with <tt>file://</tt> prepended to it, will be used. This is correct for local viewing only. +\anchor cfg_doc_abspath <dt>\c DOC_ABSPATH <dd> \addindex DOC_ABSPATH The \c DOC_ABSPATH tag should be the absolute path to the directory where the documentation is located. If left blank the directory on the local machine will be used. +\anchor cfg_bin_abspath <dt>\c BIN_ABSPATH <dd> \addindex BIN_ABSPATH The \c BIN_ABSPATH tag must point to the directory where the doxysearch binary is installed. +\anchor cfg_ext_doc_paths <dt>\c EXT_DOC_PATHS <dd> \addindex EXT_DOC_PATHS The \c EXT_DOC_PATHS tag can be used to specify one or more paths to diff --git a/doc/doxygen.sty b/doc/doxygen.sty index 33835f0..5e53104 100644 --- a/doc/doxygen.sty +++ b/doc/doxygen.sty @@ -1,3 +1,16 @@ +% +% $Id$ +% +% Copyright (C) 1997-1999 by Dimitri van Heesch. +% +% Permission to use, copy, modify, and distribute this software and its +% documentation under the terms of the GNU General Public License is hereby +% granted. No representations are made about the suitability of this software +% for any purpose. It is provided "as is" without express or implied warranty. +% See the GNU General Public License for more details. +% +% All output generated with Doxygen is not covered by this license. + \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{doxygen} \RequirePackage{calc} diff --git a/doc/doxygen_manual.tex b/doc/doxygen_manual.tex index bb8d599..01223c4 100644 --- a/doc/doxygen_manual.tex +++ b/doc/doxygen_manual.tex @@ -1,10 +1,29 @@ -\documentclass[a4paper]{article} +% +% $Id$ +% +% Copyright (C) 1997-1999 by Dimitri van Heesch. +% +% Permission to use, copy, modify, and distribute this software and its +% documentation under the terms of the GNU General Public License is hereby +% granted. No representations are made about the suitability of this software +% for any purpose. It is provided "as is" without express or implied warranty. +% See the GNU General Public License for more details. +% +% All output generated with Doxygen is not covered by this license. + +\documentclass[a4paper,ps2pdf]{article} \usepackage{a4wide} \usepackage{makeidx} \usepackage{fancyheadings} \usepackage{epsf} \usepackage{doxygen} \usepackage{multicol} +\usepackage{times} +\usepackage[backref=true, + pagebackref=true, + colorlinks=true, + linkcolor=blue + ]{hyperref} \makeindex \setcounter{tocdepth}{1} \setlength{\footrulewidth}{0.4pt} @@ -35,6 +54,7 @@ Written by Dimitri van Heesch\\[2ex] \input{doxytag_usage} \input{doxysearch_usage} \input{installdox_usage} +\input{output} \input{autolink} \input{config} \input{commands} diff --git a/doc/doxygen_usage.doc b/doc/doxygen_usage.doc index e6fee75..b9f98b3 100644 --- a/doc/doxygen_usage.doc +++ b/doc/doxygen_usage.doc @@ -41,7 +41,11 @@ doxygen <config_file> \endverbatim </ol> -If you also want a search engine to be generated, you should look +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! + +If you also want to use the search engine, you should look at section \ref doxysearch_usage. */ diff --git a/doc/faq.doc b/doc/faq.doc index c730289..3d936fe 100644 --- a/doc/faq.doc +++ b/doc/faq.doc @@ -18,12 +18,19 @@ <ol> <li><b>How do get information on the index page in HTML?</b> <p> -There is no real support for title pages at the moment. But you can -override the default index page, by using the following comment block: +You should use the \\mainpage command inside a comment block like this: \verbatim -/*! \page index My Personal Index Page +/*! \mainpage My Personal Index Page * - * This is my index personal index page. + * \section intro Introduction + * + * This is the introduction. + * + * \section install Installation + * + * \subsection step1 Step 1: Opening the box + * + * etc... */ \endverbatim @@ -44,6 +51,11 @@ around the blocks that should be hidden and put: \endverbatim in the config file then all blocks should be skipped by Doxygen as long as <code>PREPROCESSING = YES</code>. + +<li><b>How can I make doxygen ignore nasty macro's? </b> + +Look at section \ref preprocessing for the answer. + </ol> */ diff --git a/doc/index.doc b/doc/index.doc index 7a321db..dc12600 100644 --- a/doc/index.doc +++ b/doc/index.doc @@ -41,7 +41,8 @@ All output generated by Doxygen is not covered by this license. Doxygen is a documentation system for C and C++. It can generate an on-line class browser (in HTML) and/or an off-line reference manual (in \f$\mbox{\LaTeX}\f$) from a set -of documented source files. The documentation is extracted directly from the +of documented source files. There is also some support for generating +man pages. The documentation is extracted directly from the sources. Doxygen is developed on a <a href="http://www.linux.org">Linux</a> platform, but it runs on most other UNIX flavors as well. An executable for Windows 95/NT is also available. @@ -78,6 +79,8 @@ The second part forms a reference manual: <li>Section \ref doxysearch_usage shows how to use the \c doxysearch program. <li>Section \ref installdox_usage shows how to use the \c installdox script that is generated by Doxygen if you use tag files. +<li>Section \ref output shows how to generate the various output formats + supported by Doxygen. <li>Section \ref autolink shows how to put links to files, classes, and members in the documentation. <li>Section \ref config shows how to fine-tune doxygen, so it @@ -177,6 +180,8 @@ Matthias Baas, Walter Mueller, William van Dieten, Joshua Jensen, +Patrick Aberts, +Jacques Tremblay, and many others for suggestions, patches and bug reports. </ul> */ diff --git a/doc/language.doc b/doc/language.doc index f05dce3..2440a08 100644 --- a/doc/language.doc +++ b/doc/language.doc @@ -152,6 +152,31 @@ Here is a list of the languages and their current maintainers: </TR> <TR BGCOLOR="#ffffff"> <TD> + Finnish + </TD> + <TD> + Olli Korhonen + </TD> + <TD> + <a href="mailto:Olli.Korhonen@ccc.fi"> + Olli.Korhonen@ccc.fi</a> + </TD> + </TR> + <TR BGCOLOR="#ffffff"> + <TD> + Russian + </TD> + <TD> + Vladimir Vodolazkiy + </TD> + <TD> + <a href="mailto:voldemarus@geocities.com"> + voldemarus@geocities.com</a> + </TD> + </TR> + + <TR BGCOLOR="#ffffff"> + <TD> Dutch </TD> <TD> @@ -192,6 +217,10 @@ Here is a list of the languages and their current maintainers: \hline Spanish & Francisco Oltra Thennet & {\tt foltra@puc.cl} \\ \hline + Finish & Olli Korhonen & {\tt Olli.Korhonen@ccc.fi} \\ + \hline + Russian & Vladimir Vodolazkiy & {\tt voldemarus@geocities.com} \\ + \hline Dutch & Dimitri van Heesch & {\tt dimitri@stack.nl} \\ \hline \end{tabular} diff --git a/doc/output.doc b/doc/output.doc new file mode 100644 index 0000000..1e8da9e --- /dev/null +++ b/doc/output.doc @@ -0,0 +1,48 @@ +/****************************************************************************** + * + * $Id$ + * + * Copyright (C) 1997-1999 by Dimitri van Heesch. + * + * Permission to use, copy, modify, and distribute this software and its + * documentation under the terms of the GNU General Public License is hereby + * granted. No representations are made about the suitability of this software + * for any purpose. It is provided "as is" without express or implied warranty. + * See the GNU General Public License for more details. + * + * All output generated with Doxygen is not covered by this license. + * + */ +/*! \page output.html + +\section output Output Formats + +\addindex output formats + +The following output formats are \e directly supported by doxygen: +<dl> +<dt><b>HTML</b> +<dd>Generated if GENERATE_HTML is set to YES in the configuration file. +<dt>\f$\mbox{\LaTeX}\f$ +<dd>Generated if GENERATE_LATEX is set to YES in the configuration file. +<dt><b>Man pages</b> +<dd>Generated if GENERATE_MAN is set to YES in the configuration file. +</dl> + +The following output formats are \e indirectly supported by doxygen: +<dl> +<dt><b>Compressed HTML</b> (a.k.a. Windows 98 help) +<dd>Generated by Microsoft's HTML Help workshop from the HTML output if + \c GENERATE_HTMLHELP is set to \c YES. +<dt><b>Postscript</b> +<dd>Generated from the \f$\mbox{\LaTeX}\f$ output by + running <code>make ps</code> in the output directory. + For the best results \c PDF_HYPERLINKS should be set to \c NO. +<dt><b>PDF</b>\htmlonly \endhtmlonly +<dd>Generated from the \f$\mbox{\LaTeX}\f$ output by + running <code>make pdf</code> in the output directory. + In order to get hyperlinks in the pdf file, + \c PDF_HYPERLINKS should be set to \c YES. +</dl> + +*/ diff --git a/doc/starting.doc b/doc/starting.doc index bbb23bd..e89f717 100644 --- a/doc/starting.doc +++ b/doc/starting.doc @@ -203,7 +203,7 @@ 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_MEMBER_DESC to \c NO in +(this description can be omitted by setting \c BRIEF_STDMETHOD_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). @@ -443,7 +443,7 @@ after preprocessing becomes: \endverbatim Notice that doxygen will now expand \e all macro definitions -(recursively if needed). This is often too much, therefore doxygen also +(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 and specify the macro definitions after the \c PREDEFINED tag. @@ -462,9 +462,9 @@ of an abstract base class called \c IUnknown: /*! The IUnknown interface */ DECLARE_INTERFACE(IUnknown) { - MEMBER(HRESULT,QueryInterface) (THIS_ REFIID iid, void **ppv) PURE; - MEMBER(ULONG,AddRef) (THIS) PURE; - MEMBER(ULONG,Release) (THIS) PURE; + STDMETHOD(HRESULT,QueryInterface) (THIS_ REFIID iid, void **ppv) PURE; + STDMETHOD(ULONG,AddRef) (THIS) PURE; + STDMETHOD(ULONG,Release) (THIS) PURE; }; \endverbatim @@ -479,7 +479,7 @@ ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES PREDEFINED = "DECLARE_INTERFACE(name)=class name" \ - "MEMBER(result,name)=virtual result name" \ + "STDMETHOD(result,name)=virtual result name" \ "PURE= = 0" \ THIS_= \ THIS= \ diff --git a/doc/trouble.doc b/doc/trouble.doc index 5f130ec..f02914b 100644 --- a/doc/trouble.doc +++ b/doc/trouble.doc @@ -48,8 +48,8 @@ int *(a[20]); \endverbatim then doxygen will remove the braces and correctly parse the result. -<li>Not all names in code fragments that are include in the documentation - are replaced by links (for instance when using SOURCE_BROWSER = YES). +<li>Not all names in code fragments that are included in the documentation + are replaced by links (for instance when using \c SOURCE_BROWSER = \c YES). For a part this is because the code parser isn't smart enough at the moment. I'll try to improve this in the future. But even with these improvements not everthing can be properly linked to the corresponding |