diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/commands.doc | 27 | ||||
| -rw-r--r-- | doc/config.doc | 26 | ||||
| -rw-r--r-- | doc/doxytag_usage.doc | 2 | ||||
| -rw-r--r-- | doc/faq.doc | 27 | ||||
| -rw-r--r-- | doc/index.doc | 24 | ||||
| -rw-r--r-- | doc/install.doc | 32 | ||||
| -rw-r--r-- | doc/output.doc | 8 | ||||
| -rw-r--r-- | doc/starting.doc | 20 |
8 files changed, 137 insertions, 29 deletions
diff --git a/doc/commands.doc b/doc/commands.doc index e817483..1efd378 100644 --- a/doc/commands.doc +++ b/doc/commands.doc @@ -93,6 +93,7 @@ documentation: <li> \refitem cmdskipline \skipline <li> \refitem cmdstruct \struct <li> \refitem cmdsubsection \subsection +<li> \refitem cmdthrow \throw <li> \refitem cmdtypedef \typedef <li> \refitem cmdunion \union <li> \refitem cmduntil \until @@ -229,6 +230,12 @@ Doxygen. Unrecognized commands are treated as normal text. documentation contained in the comment block. All examples are placed in a list. The source code is scanned for documented members and classes. If any are found, the names are cross-referenced with the documentation. + Source files or directories can be specified using the + \c EXAMPLE_PATH tag of Doxygen's configuration file. + + If \<file-name\> itself is not unique for the set of example files specified + by the \c EXAMPLE_PATH tag, you can include part of the absolute path + to disambiguate it. If more that one source file is needed for the example, the \\include command can be used. @@ -583,9 +590,21 @@ Doxygen. Unrecognized commands are treated as normal text. sectioning command is encountered. See section \ref cmdfn "\\fn" for an example. + \par Note: + the tag \\exceptions is a synonym for this tag. + \sa Section \ref cmdjdexception "@exception". <hr> +\subsection cmdthrow \throw <exception-object> { exception description } + + \addindex \throw + Equivalent to \\exception (see section \ref cmdexception "\\exception"). + + \par Note: + the tag \\throws is a synonym for this tag. + +<hr> \subsection cmdreturn \return { description of the return value } \addindex \return @@ -799,6 +818,10 @@ Doxygen. Unrecognized commands are treated as normal text. Source files or directories can be specified using the \c EXAMPLE_PATH tag of Doxygen's configuration file. + If \<file-name\> itself is not unique for the set of example files specified + by the \c EXAMPLE_PATH tag, you can include part of the absolute path + to disambiguate it. + Using the \\include command is equivalent to inserting the file into the documentation block and surrounding it with \\code and \\endcode commands. @@ -1199,6 +1222,10 @@ The following command JavaDoc command are support. \subsection cmdjdexception @exception <exception-object> { exception-description } \addindex @exception Equivalent to \\exception (see section \ref cmdexception "\\exception"). + Also synonymous to \@exceptions and \\exceptions. +\subsection cmdjdthrows @throw <exception-object> { exception-description } + Equivalent to \\throw (see section \ref cmdthrow "\\throw"). + Also synonymous to \@exception and \\exception. \subsection cmdjdreturn @return { description of the return value } \addindex @return Equivalent to \\return (see section \ref cmdreturn "\\return"). diff --git a/doc/config.doc b/doc/config.doc index 5add2e7..80089a4 100644 --- a/doc/config.doc +++ b/doc/config.doc @@ -91,6 +91,7 @@ followed by the descriptions of the tags grouped by category. <li> \refitem cfg_include_path INCLUDE_PATH <li> \refitem cfg_inherit_docs INHERIT_DOCS <li> \refitem cfg_inline_info INLINE_INFO +<li> \refitem cfg_inline_sources INLINE_SOURCES <li> \refitem cfg_input INPUT <li> \refitem cfg_input_filter INPUT_FILTER <li> \refitem cfg_internal_docs INTERNAL_DOCS @@ -273,9 +274,14 @@ followed by the descriptions of the tags grouped by category. \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. + If the \c SOURCE_BROWSER tag is set to \c YES then a list of source files will + be generated. Documented entities will be cross-referenced with these sources. + +\anchor cfg_inline_sources +<dt>\c INLINE_SOURCES <dd> + \addindex INLINE_SOURCES + Setting the \c INLINE_SOURCES tag to \c YES will include the body + of functions, classes and enums directly into the documentation. \anchor cfg_case_sense_names <dt>\c CASE_SENSE_NAMES <dd> @@ -698,9 +704,23 @@ EXTRA_PACKAGES = times <dt>\c TAGFILES <dd> \addindex TAGFILES The \c TAGFILES tag can be used to specify one or more tagfiles. + See section \ref doxytag_usage for more information about the usage of tag files. + Optionally an initial location of the external documentation + can be added for each tagfile. + The format of a tag file without this location is as follows: + <pre> +TAGFILES = file1 file2 ... </pre> + Adding location for the tag files is done as follows: + <pre> +TAGFILES = file1=loc1 "file2 = loc2" ... </pre> + where \c loc1 and \c loc2 can be relative or absolute paths or URLs, + If a location is present for each tag, the installdox tool (see + section \ref installdox_usage for more information) does not + have to be run to correct the links. + \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 diff --git a/doc/doxytag_usage.doc b/doc/doxytag_usage.doc index cbccce8..ce3eae3 100644 --- a/doc/doxytag_usage.doc +++ b/doc/doxytag_usage.doc @@ -85,7 +85,7 @@ doxytag -t example.tag example/html documentation. Because the tag file does not specify where the documentation is located, you will have to specify that by running the installdox script that doxygen generates - (See \ref installdox_usage for more information). + (See section \ref installdox_usage for more information). Note that this is actually a feature because if you (or someone else) moves the external documentation to a different diff --git a/doc/faq.doc b/doc/faq.doc index 123671f..be47ce5 100644 --- a/doc/faq.doc +++ b/doc/faq.doc @@ -75,6 +75,33 @@ To make doxygen put <br><br> in the documentation of the class MyClassName regardless of the name of the actual header file in which the definition of MyClassName is contained. +<li><b>How can I use tag files in combination with compressed HTML</b> + +If you want to refer from one compressed HTML file +\c a.chm to another compressed HTML file +called \c b.chm, the +link in \c a.chm must have the following format: +\verbatim +<a href="b.chm::/file.html"> +\endverbatim +Unfortunately this only works if both compressed HTML files are in the same +directory. + +As a result you must rename the generated \c index.chm files for all projects +into something unique and put all \c .chm files in one directory. + +Suppose you have a project \e a referring to a project \e b using tag file +\c b.tag, then you could rename the \c index.chm for project \e a into +\c a.chm and the \c index.chm for project \e b into \c b.chm. In the +configuration file for project \e a you write: +\verbatim +TAGFILES = b.tag=b.chm:: +\endverbatim +or you can use \c installdox to set the links as follows: +\verbatim +installdox -lb.tag@b.chm:: +\endverbatim + </ol> */ diff --git a/doc/index.doc b/doc/index.doc index efbcfe7..640129b 100644 --- a/doc/index.doc +++ b/doc/index.doc @@ -33,7 +33,10 @@ 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. +See the +<a href="http://www.gnu.org/copyleft/gpl.html"> +GNU General Public License</a> +for more details. <p> All output generated by Doxygen is not covered by this license. @@ -41,11 +44,13 @@ 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. There is also some support for generating -man pages. The documentation is extracted directly from the +of documented source files. There is also support for generating +man pages and for converting the generated output into +Postscript, hyperlinked PDF or compressed HTML. +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. +An executable for Windows 9x/NT is also available. Doxygen can also be configured to extract the code-structure from undocumented source files. This can be very useful to quickly find your way in large @@ -106,6 +111,17 @@ list of projects that use doxygen (see {\tt http://www.stack.nl/$\sim$dimitri/do \endlatexonly If you know other projects, let me know and I'll add them. +<h2>Future work</h2> +Although doxygen is used successfully by a lot of people already, +there is always room for improvement. Therefore, I have compiled a +\htmlonly +<a href="http://www.stack.nl/~dimitri/doxygen/todo.html">todo/wish list</a> +\endhtmlonly +\latexonly +todo/wish list (see {\tt http://www.stack.nl/$\sim$dimitri/doxygen/todo.html}) +\endlatexonly +of possible and/or requested enhancements. + <h2>Acknowledgements</h2> \addindex acknowledgements Thanks go to: diff --git a/doc/install.doc b/doc/install.doc index b17be97..1c5171a 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -29,7 +29,6 @@ following to build the executable: \addindex Qt <LI>The <a href="ftp://prep.ai.mit.edu/pub/gnu">GNU</a> tools flex, bison and make - \latexonly(see {\tt ftp://prep.ai.mit.edu/pub/gnu})\endlatexonly. \addindex flex \addindex bison \addindex make @@ -38,6 +37,8 @@ following to build the executable: \latexonly(see {\tt http://www.perl.com})\endlatexonly. \addindex perl </UL> +For platform specific installation instructions see the \c INSTALL file +that is included in the package. \addindex HTTP \addindex CGI @@ -45,17 +46,25 @@ To use the search engine \c doxysearch, you will also need a HTTP daemon running on the target system and permission to execute a CGI binary. -Once you have Qt installed correctly, you can simply enter: +If you are running Unix, and have Qt installed correctly, you can simply enter \verbatim -make +configure \endverbatim -to get a list of all supported platforms/compilers. -Typing <tt>make</tt> followed by your platform will compile doxygen. -For Linux you can enter the following: +to set up the makefiles for your platform. For Windows this step can be +skipped. + +To override the auto detected platform you can specify \verbatim -make linux-g++ +configure --platform platform-type \endverbatim +See the \c PLATFORMS file for a list of possible platforms. +For more configuration options use <code>configure --help</code> +To compile and link the sources enter +\verbatim +make +\endverbatim +in the root of the distribution. Doxygen should compile without errors or warnings. If it does not, please send the compilation errors or warnings along with a description of your platform to @@ -67,6 +76,11 @@ You may want to copy these files to a location in your path (\c /usr/local/bin for instance) or add the \c bin directory of the distribution to your search path. +On Unix you can also type: +\verbatim +make install +\endverbatim + The following binaries should now be available: <UL> <LI>\c doxygen: for generating the class browser. @@ -85,8 +99,8 @@ Doxygen was developed and tested under Linux using the following tools: <li>GNU make version 3.76.1 <li>Perl version 5.005_02 <li>VIM version 5.4 -<li>Netscape 4.04 & 4.5 -<li>Troll Tech's tmake version 1.2 (included in the distribution) +<li>Netscape 4.61 +<li>Troll Tech's tmake version 1.3 (included in the distribution) <li>teTeX version 0.9 </ul> diff --git a/doc/output.doc b/doc/output.doc index 1e8da9e..7ddaf8d 100644 --- a/doc/output.doc +++ b/doc/output.doc @@ -22,11 +22,11 @@ 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. +<dd>Generated if \c GENERATE_HTML is set to \c YES in the configuration file. <dt>\f$\mbox{\LaTeX}\f$ -<dd>Generated if GENERATE_LATEX is set to YES in the configuration file. +<dd>Generated if \c GENERATE_LATEX is set to \c YES in the configuration file. <dt><b>Man pages</b> -<dd>Generated if GENERATE_MAN is set to YES in the configuration file. +<dd>Generated if \c GENERATE_MAN is set to \c YES in the configuration file. </dl> The following output formats are \e indirectly supported by doxygen: @@ -42,7 +42,7 @@ The following output formats are \e indirectly supported by doxygen: <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. + \c PDF_HYPERLINKS should be set to \c YES in the configuration file. </dl> */ diff --git a/doc/starting.doc b/doc/starting.doc index 293f6b2..4f707c7 100644 --- a/doc/starting.doc +++ b/doc/starting.doc @@ -46,8 +46,9 @@ 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 \<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>). +If you use <code>-</code> (i.e. the minus sign) 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: @@ -82,7 +83,9 @@ 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. +generate such cross-references if you set the \c SOURCE_BROWSER tag to \c YES. +It can also include the sources directly into the documentation by setting +\c INLINE_SOURCES to \c YES (this can be handly for code reviews for instance). \subsection step2 Step 2: Running doxygen @@ -120,10 +123,11 @@ By typing \c make in the \c latex directory the dvi file \c refman.dvi 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 ). Conversion to PDF is also possible; just type -<code>make pdf</code>. The Postscript file can be send to a postscript +(this requires \c dvips ). 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. +Conversion to PDF is also possible; just type +<code>make pdf</code>. To get the best results for PDF output you should set the \c PDF_HYPERLINKS tag to \c YES. @@ -436,7 +440,7 @@ Then by default doxygen will feed the following to its parser: #define VERSION #define CONST_STRING - static CONST_STRING version = "1.xx"; + static CONST_STRING version = "2.xx"; \endverbatim You can disable all preprocessing by setting \c ENABLE_PREPROCESSING to \c @@ -541,8 +545,8 @@ PREDEFINED = QListT:=QList \endverbatim As you can see doxygen's preprocessor is quite powerful, but if you want -even more flexibility you can always write an input filter and specify it on -the \c INPUT_FILTER flag. +even more flexibility you can always write an input filter and specify it +after the \c INPUT_FILTER tag. \subsection moreinfo More information |