diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/custcmd.doc | 123 | ||||
-rw-r--r-- | doc/index.doc | 2 | ||||
-rw-r--r-- | doc/install.doc | 59 |
3 files changed, 163 insertions, 21 deletions
diff --git a/doc/custcmd.doc b/doc/custcmd.doc new file mode 100644 index 0000000..15b7d06 --- /dev/null +++ b/doc/custcmd.doc @@ -0,0 +1,123 @@ +/****************************************************************************** + * + * + * + * Copyright (C) 1997-2007 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. + * + * Documents produced by Doxygen are derivative works derived from the + * input used in their production; they are not affected by this license. + * + */ +/*! \page custcmd Custom Commands + +Doxygen provides a large number of \ref commands "special commands", +\ref xmlcmds "XML commands", and \ref htmlcmds "HTML commands". +that can be used to enhance or structure the documentation inside a comment block. +If you for some reason have a need to define new commands you can do +so by means of an \e alias definition. + +The definition of an alias should be specified in the configuration file using +the \ref cfg_aliases "ALIASES" configuration tag. + +\section custcmd_simple Simple aliases +The simplest form of an alias is a simple substitution of the form +\verbatim + name=value +\endverbatim + For example defining the following alias: +\verbatim + ALIASES += sideeffect="\par Side Effects:\n" +\endverbatim + will allow you to + put the command \\sideeffect (or \@sideeffect) in the documentation, which + will result in a user-defined paragraph with heading <b>Side Effects:</b>. + +Note that you can put \\n's in the value part of an alias to insert newlines. + +Also note that you can redefine existing special commands if you wish. + +Some commands, such as \ref cmdxrefitem "\\xrefitem" are designed to be used in +combination with aliases. + +\section custcmd_complex Aliases with arguments +Aliases can also have one or more arguments. In the alias definition you then need +to specify the number of arguments between curly braces. In the value part of the +definition you can place \\x markers, where 'x' represents the argument number starting +with 1. + +Here is an example of an alias definition with a single argument: +\verbatim +ALIASES += l{1}="\ref \1" +\endverbatim + +Inside a comment block you can use it as follows +\verbatim +/** See \l{SomeClass} for more information. */ +\endverbatim +which would be the same as writing +\verbatim +/** See \ref SomeClass for more information. */ +\endverbatim + +Note that you can overload an alias by a version with multiple arguments, for instance: +\verbatim +ALIASES += l{1}="\ref \1" +ALIASES += l{2}="\ref \1 \"\2\"" +\endverbatim +Note that the quotes inside the alias definition have to be escaped with a backslash. + +With these alias definitions, we can write +\verbatim +/** See \l{SomeClass,Some Text} for more information. */ +\endverbatim +inside the comment block and it will expand to +\verbatim +/** See \ref SomeClass "Some Text" for more information. */ +\endverbatim +where the command with a single argument would still work as shown before. + +Aliases can also be expressed in terms of other aliases, e.g. a new command +\\reminder can be expressed as a \\xrefitem via an intermediate \\xreflist command +as follows: +\verbatim +ALIASES += xreflist{3}="\xrefitem \1 \"\2\" \"\3\" " \ +ALIASES += reminder="\xreflist{reminders,Reminder,Reminders}" \ +\endverbatim + +Note that if for aliases with more than one argument a comma is used as a separator, +if you want to put a comma inside the command, you will need to escape it with a backslash, +i.e. +\verbatim +\l{SomeClass,Some text\, with an escaped comma} +\endverbatim +given the alias definition of \\l in the example above. + +\section custcmd_nesting Nesting custom command + +You can use commands as arguments of aliases, including commands +defined using aliases. + +As an example consider the following alias definitions + +\verbatim +ALIASES += Bold{1}="<b>\1</b>" +ALIASES += Emph{1}="<em>\1</em>" +\endverbatim + +Inside a comment block you can now use: +\verbatim +/** This is a \Bold{bold \Emph{and} Emphasized} text fragment. */ +\endverbatim +which will expand to +\verbatim +/** This is a <b>bold <em>and</em> Emphasized</b> text fragment. */ +\endverbatim + + +*/ diff --git a/doc/index.doc b/doc/index.doc index faed772..3c4eae3 100644 --- a/doc/index.doc +++ b/doc/index.doc @@ -192,8 +192,6 @@ Thanks go to: <li>Talin for adding support for C# style comments with XML markup. <li>Petr Prikryl for coordinating the internationalisation support. All language maintainers for providing translations into many languages. -<li>Gerald Steffens of <a href="http://www.e-trend.de">E-trend</a> - for financial support. <li>The band <a href="http://www.porcupinetree.com">Porcupine Tree</a> for providing hours of great music to listen to while coding. <li>many, many others for suggestions, patches and bug reports. diff --git a/doc/install.doc b/doc/install.doc index 3c75386..b8cb8ff 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -366,40 +366,61 @@ before running make. \section install_src_windows Compiling from source on Windows From version 1.5.0 onwards, build files are provided for Visual Studio 2005. -Also the free "Express" version of Developer Studio can be used to compile doxygen. -Alternatively, you can compile doxygen \ref install_src_unix "the Unix way" using +Also the free (as in beer) "Express" version of Developer Studio can be used to +compile doxygen. Alternatively, you can compile doxygen +\ref install_src_unix "the Unix way" using <a href="http://en.wikipedia.org/wiki/Cygwin">Cygwin</a> or <a href="http://www.mingw.org/">MinGW</a>. Before you can compile doxygen you need to download and install the C++ compiler of Visual Studio. Since Microsoft apparently wants to lure everyone into using their -.NET stuff, you need to +.NET stuff, they made things somewhat difficult when you use the Express version. +You need to <a href="http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/"> do some manual steps</a> in order to setup a proper working environment for building -native win32 applications. - -Once your environment is setup, you -can <a href="http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc">download</a> -the source distribution of doxygen and unpack it. -If you don't have a tool like WinZip, then I suggest to download -<a href="http://sourceforge.net/projects/unxutils/">unxutils</a> -and untar the archive from within a command box using +native win32 applications such as Doxygen. + +The next step is to install unxutils (see http://sourceforge.net/projects/unxutils). +This packages contains the tools \c flex and \c bison which are needed during the +compilation process if you use a CVS snapshot of doxygen (the official source releases +come with pre-generated sources). +Download the zip extract it to e.g. <code>c:\\tools\\unxutils</code>. + +Now you need to add/adjust the following environment variables +(via Control Panel/System/Advanced/Environment Variables): +- add <code>c:\\tools\\unxutils\\usr\\local\\wbin;</code> to the start of <code>PATH</code> +- set <code>BISON_SIMPLE</code> to <code>c:\\tools\\unxutils\\usr\\share\\bison.simple</code> + +Download doxygen's source tarball and put it somewhere (e.g use <code>c:\\tools</code>) + +Now start a new command shell and type \verbatim - tar zxvf doxygen-version.src.tar.gz +cd c:\tools +gunzip doxygen-x.y.z.src.tar.gz +tar xvf doxygen-x.y.z.src.tar \endverbatim -Inside the archive you will find a \c winbuild directory containing a \c Doxygen.sln -file. Just open this file in Visual Studio. You can now build the Doxygen, Doxytag, -and Doxywizard projects for Release or Debug to compile the executables. +to unpack the sources. + +Now your environment is setup to build \c doxygen and \c doxytag. + +Inside the \c doxygen-x.y.z directory you will find a \c winbuild directory +containing a \c Doxygen.sln file. Open this file in Visual Studio. +You can now build the Release or Debug flavor of Doxygen and Doxytag by right-clicking +the project in the solutions explorer, and selecting Build. -Note that compiling Doxywizard currently requires a <a href="http://www.trolltech.com/products/qt/qt3"> -commercial license for Qt 3</a>. +Note that compiling Doxywizard currently requires Qt version 3 +(see http://www.trolltech.com/products/qt/qt3). +If you do not have a commercial license, you can build Doxywizard with the open +source version (see http://qtwin.sourceforge.net/qt3-win32/compile-msvc-2005.php), +but I have not tried this myself. -Also read the next section for additional tools you may need to install. +Also read the next section for additional tools you may need to install to run +doxygen with certain features enabled. <!-- Currently, I have only compiled doxygen for Windows using Microsoft's -Visual C++ (version 6.0). For other compilers you may need to edit the +Visual C++ (). For other compilers you may need to edit the perl script in <code>wintools/make.pl</code> a bit. Let me know what you had to change if you got Doxygen working with another compiler. If you have Visual Studio you can also use the .dsw file found in |