diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/config.doc | 8 | ||||
| -rw-r--r-- | doc/docblocks.doc | 46 | ||||
| -rw-r--r-- | doc/install.doc | 33 | ||||
| -rw-r--r-- | doc/language.doc | 8 |
4 files changed, 60 insertions, 35 deletions
diff --git a/doc/config.doc b/doc/config.doc index afe2b8e..b819f53 100644 --- a/doc/config.doc +++ b/doc/config.doc @@ -164,6 +164,7 @@ followed by the descriptions of the tags grouped by category. <li> \refitem cfg_rtf_stylesheet_file RTF_STYLESHEET_FILE <li> \refitem cfg_search_includes SEARCH_INCLUDES <li> \refitem cfg_searchengine SEARCHENGINE +<li> \refitem cfg_short_names SHORT_NAMES <li> \refitem cfg_show_include_files SHOW_INCLUDE_FILES <li> \refitem cfg_show_used_files SHOW_USED_FILES <li> \refitem cfg_sort_member_docs SORT_MEMBER_DOCS @@ -351,6 +352,13 @@ followed by the descriptions of the tags grouped by category. classes or files whose names only differ in case and if your file system supports case sensitive file names. +\anchor cfg_short_names +<dt>\c SHORT_NAMES <dd> + \addindex SHORT_NAMES + If the \c SHORT_NAMES tag is set to \c YES, doxygen will generate much shorter + (but less readable) file names. This can be useful is your file systems + doesn't support long names like on DOS, Mac, or CD-ROM. + \anchor cfg_hide_scope_names <dt>\c HIDE_SCOPE_NAMES <dd> \addindex HIDE_SCOPE_NAMES diff --git a/doc/docblocks.doc b/doc/docblocks.doc index 95d13b5..d2df482 100644 --- a/doc/docblocks.doc +++ b/doc/docblocks.doc @@ -43,7 +43,7 @@ The following types of special documentation blocks are supported by doxygen: Doxygen only allows one brief and one detailed description. If there is one brief description before a declaration and one before a definition, only the one before the \e declaration will be used. If -the same situation occurs for a detail description, +the same situation occurs for a detailed description, the one before the \e definition is preferred and the one before the declaration will be ignored. @@ -56,14 +56,15 @@ Here is an example of a documented piece of C++ code using the Qt style: 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 hidden by - setting \ref cfg_brief_member_desc "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 \ref cfg_repeat_brief "REPEAT_BRIEF" tag -to \c NO). Both the brief and the detailed descriptions are optional +Note that consecutive one-line comments are merged together in one brief +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 hidden by setting +\ref cfg_brief_member_desc "BRIEF_MEMBER_DESC" to \c NO in +the config file). By default the brief descriptions become the first +sentence of the detailed descriptions +(but this can be changed by setting the \ref cfg_repeat_brief "REPEAT_BRIEF" +tag to \c NO). Both the brief and the detailed descriptions are optional for the Qt style. By default a JavaDoc style documentation block behaves the same way as a @@ -71,7 +72,7 @@ Qt style documentation block. This is not according the JavaDoc specification however, where the first sentence of the documentation block is automatically treated as a brief description. To enable this behaviour you should set \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" to YES in the configuration -file. If you enble this option and want to put a dot in the middle of a +file. If you enable this option and want to put a dot in the middle of a sentence without ending it, you should put a backslash and a space after it. Here is an example: \verbatim @@ -112,7 +113,8 @@ of a function or inside a normal C style comment block), as long as you put a structural command inside the documentation block. Structural commands (like all other commands) start with a backslash -(<tt>\\</tt>) followed by a command name and one or more parameters. +(<tt>\\</tt>), or an at-sign (<tt>\@</tt>) in JavaDoc style, +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: @@ -124,7 +126,7 @@ in the input that is read by doxygen: */ \endverbatim -Here the special command \c \class is used to indicated that the +Here the special command \c \class is used to indicate that the comment block contains documentation for the class \c Test. Other structural commands are: <ul> @@ -142,11 +144,17 @@ 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 -itself. The same holds for namespaces. To document a C function, typedef, +itself. The same holds for namespaces. To document a global C function, typedef, enum or preprocessor definition you must first document the file that contains it (usually this will be a header file, because that file contains the information that is exported to other source files). +Let's repeat that, because it is often overlooked: +to document global objects (functions, typedefs, enum, macros, etc), you +<em>must</em> document the file in which they are defined. In other words, +there <em>must</em> at least be a \verbatim /*! \file */ \endverbatim +or a \verbatim /** @file */ \endverbatim line in this file. + Here is an example of a C header named \c structcmd.h that is documented using structural commands: \verbinclude structcmd.h @@ -164,7 +172,7 @@ using structural commands: \subsection memberdoc Documenting compound members. -If you want to document the members of a file, struct, union, class, or enum +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 @@ -172,7 +180,7 @@ additional comment blocks: \verbatim /*!< ... */ \endverbatim -This block can be used to put a qt style documentation blocks after a member. +This block can be used to put a Qt style documentation blocks after a member. The one line version look as follows: \verbatim //!< ... @@ -189,7 +197,7 @@ 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. -Here is an example of a the use of these comment blocks: +Here is an example of the use of these comment blocks: \verbinclude afterdoc.h \htmlonly Click <a href="$(DOXYGEN_DOCDIR)/examples/afterdoc/html/class_test.html">here</a> @@ -198,9 +206,9 @@ Here is an example of a the use of these comment blocks: \warning These blocks can only be used to document \e members. They cannot be used to document files, classes, unions, structs, - groups, namespaces and enums. Furthermore, the structural commands - mentioned in the previous section (like <code>\\class</code>) are ignored - inside these comment blocks. + groups, namespaces and enums themselves. Furthermore, the structural + commands mentioned in the previous section + (like <code>\\class</code>) are ignored inside these comment blocks. \htmlonly Go to the <a href="lists.html">next</a> section or return to the diff --git a/doc/install.doc b/doc/install.doc index fe05177..30acc5c 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -358,11 +358,18 @@ Here is what is required: <li>The GNU tools flex, bison, and sed. To get these working on Windows you should install the <a href="http://sources.redhat.com/cygwin/">cygwin tools</a> - \latexonly(see {\tt http://sources.redhat.com/cygwin/})\endlatexonly. + \latexonly(see {\tt http://sources.redhat.com/cygwin/})\endlatexonly + + Alternatively, you can also choose to + download only a <a href="http://www.doxygen.org/dl/cygwin_tools.zip">small subset</a> + \latexonly(see {\tt http://www.doxygen.org/dl/cygwin_tools.zip})\endlatexonly + of the cygwin tools that I put together just to compile doxygen. Make sure the <code>BISONLIB</code> environment variable points to the location where the files <code>bison.simple</code> and - <code>bison.hairy</code> are located. + <code>bison.hairy</code> are located. For instance if these files are in + <code>c:\\tools\\cygwin\\share</code> then BISONLIB should + be set to <code>//c/tools/cygwin/share/</code> Also make sure the tools are available from a dos box, by adding the directory they are in to the search path. @@ -377,16 +384,18 @@ Here is what is required: using WinZip -- as mentioned at the beginning of this list of steps. -<li>Since Doxygen-1.2.2-20001015, the distribution includes the part - of Qt-2.x.x that is needed for compilation of doxygen, doxytag, - and doxysearch. The missing files for Windows were also created. - This allows compilation of doxygen on systems without X11 or the - full Qt. For doxywizard Qt-2.2 is still required however. - - You may be interested in the professional license of - <A HREF="http://www.trolltech.com/products/qt.html">Qt for Windows</A> - \latexonly\par (see - {\tt http://www.trolltech.com/products/qt.html})\endlatexonly. +<li>From Doxygen-1.2.2-20001015 onwards, the distribution includes the part + of Qt-2.x.x that is needed for to compile doxygen, doxytag, + and doxysearch. The Windows specific part were also created. + As a result doxygen can be compiled on systems without X11 or the + commerical version of Qt. + + For doxywizard, a complete Qt library this is + still a requirement however. You may be interested in the professional + license of <A HREF="http://www.trolltech.com/products/qt.html">Qt for + Windows</A> \latexonly\par (see + {\tt http://www.trolltech.com/products/qt.html})\endlatexonly. If you + donate me a professional license I'll port doxywizard for you :-) <li>To generate LaTeX documentation or formulas in HTML you need the tools: <code>latex</code>, <code>dvips</code> and <code>gswin32</code>. diff --git a/doc/language.doc b/doc/language.doc index 595fa4e..d7b3a53 100644 --- a/doc/language.doc +++ b/doc/language.doc @@ -148,11 +148,11 @@ Here is a list of the languages and their current maintainers: Russian </TD> <TD> - Andrey V. Stolyarov + Alexandr Chelpanov </TD> <TD> - <a href="mailto:crocodil@NOSPAM.croco.net"> - crocodil@NOSPAM.croco.net</a> + <a href="mailto:cav@NOSPAM.cryptopro.ru"> + cav@NOSPAM.cryptopro.ru</a> </TD> </TR> <TR BGCOLOR="#ffffff"> @@ -246,7 +246,7 @@ Here is a list of the languages and their current maintainers: \hline Finnish & Olli Korhonen & {\tt Olli.Korhonen@ccc.fi} \\ \hline - Russian & Andrey V. Stolyarov & {\tt crocodil@croco.net} \\ + Russian & Alexandr Chelpanov & {\tt cav@cryptopro.ru} \\ \hline Korean & Richard Kim & {\tt ryk@dspwiz.com} \\ \hline |