|
Packit Service |
50c9f2 |
/******************************************************************************
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* Copyright (C) 1997-2015 by Dimitri van Heesch.
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* Permission to use, copy, modify, and distribute this software and its
|
|
Packit Service |
50c9f2 |
* documentation under the terms of the GNU General Public License is hereby
|
|
Packit Service |
50c9f2 |
* granted. No representations are made about the suitability of this software
|
|
Packit Service |
50c9f2 |
* for any purpose. It is provided "as is" without express or implied warranty.
|
|
Packit Service |
50c9f2 |
* See the GNU General Public License for more details.
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* Documents produced by Doxygen are derivative works derived from the
|
|
Packit Service |
50c9f2 |
* input used in their production; they are not affected by this license.
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
*/
|
|
Packit Service |
50c9f2 |
/*! \page faq Frequently Asked Questions
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\tableofcontents
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_index How to get information on the index page in HTML?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
You should use the \ref cmdmainpage "\\mainpage" command inside a comment block like this:
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
/*! \mainpage My Personal Index Page
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* \section intro_sec Introduction
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* This is the introduction.
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* \section install_sec Installation
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* \subsection step1 Step 1: Opening the box
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* etc...
|
|
Packit Service |
50c9f2 |
*/
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section fac_al Help, some/all of the members of my class / file / namespace are not documented?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Check the following:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Is your class / file / namespace documented? If not, it will not
|
|
Packit Service |
50c9f2 |
be extracted from the sources unless \ref cfg_extract_all "EXTRACT_ALL" is set to \c YES
|
|
Packit Service |
50c9f2 |
in the config file.
|
|
Packit Service |
50c9f2 |
Are the members private? If so, you must set \ref cfg_extract_private "EXTRACT_PRIVATE" to \c YES
|
|
Packit Service |
50c9f2 |
to make them appear in the documentation.
|
|
Packit Service |
50c9f2 |
Is there a function macro in your class that does not end with a
|
|
Packit Service |
50c9f2 |
semicolon (e.g. MY_MACRO())? If so then you have to instruct
|
|
Packit Service |
50c9f2 |
doxygen's preprocessor to remove it.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
This typically boils down to the following settings in the config file:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
ENABLE_PREPROCESSING = YES
|
|
Packit Service |
50c9f2 |
MACRO_EXPANSION = YES
|
|
Packit Service |
50c9f2 |
EXPAND_ONLY_PREDEF = YES
|
|
Packit Service |
50c9f2 |
PREDEFINED = MY_MACRO()=
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Please read the \ref preprocessing "preprocessing" section of the
|
|
Packit Service |
50c9f2 |
manual for more information.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_extract_all When I set EXTRACT_ALL to NO none of my functions are shown in the documentation.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
In order for global functions, variables, enums, typedefs, and defines
|
|
Packit Service |
50c9f2 |
to be documented you should document the file in which these commands are
|
|
Packit Service |
50c9f2 |
located using a comment block containing a \ref cmdfile "\\file" (or \ref cmdfile "\@file")
|
|
Packit Service |
50c9f2 |
command.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Alternatively, you can put all members in a group (or module)
|
|
Packit Service |
50c9f2 |
using the \ref cmdingroup "\\ingroup" command and then document the group using a comment
|
|
Packit Service |
50c9f2 |
block containing the \ref cmddefgroup "\\defgroup" command.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
For member functions or functions that are part of a namespace you should
|
|
Packit Service |
50c9f2 |
document either the class or namespace.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_ext_mapping My file with a custom extension is not parsed (properly) (anymore).
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen only parses files that are specified as input (via the \ref cfg_input "INPUT" tag)
|
|
Packit Service |
50c9f2 |
and that match a specified extension (mentioned in \ref cfg_file_patterns "FILE_PATTERNS")
|
|
Packit Service |
50c9f2 |
The list of files is then reduced by excluding files listed as \ref cfg_exclude "EXCLUDE" or
|
|
Packit Service |
50c9f2 |
files that match the patterns set by \ref cfg_exclude_patterns "EXCLUDE_PATTERNS".
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
In the past doxygen parsed all files with an unknown extension as C files which could lead to
|
|
Packit Service |
50c9f2 |
undesired results. Since version 1.8.8, doxygen requires that you specify a mapping that tells
|
|
Packit Service |
50c9f2 |
for a certain file extension, which parser to use.
|
|
Packit Service |
50c9f2 |
This mapping is specified using the \ref cfg_extension_mapping "EXTENSION_MAPPING" tag.
|
|
Packit Service |
50c9f2 |
If no mapping is specified the file's contents will be ignored.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_code How can I make doxygen ignore some code fragment?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The new and easiest way is to add one comment block
|
|
Packit Service |
50c9f2 |
with a \ref cmdcond "\\cond" command at the start and one comment block
|
|
Packit Service |
50c9f2 |
with a \ref cmdendcond "\\endcond" command at the end of the piece of
|
|
Packit Service |
50c9f2 |
code that should be ignored. This should be within the same file of course.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
But you can also use doxygen's preprocessor for this:
|
|
Packit Service |
50c9f2 |
If you put
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
#ifndef DOXYGEN_SHOULD_SKIP_THIS
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
/* code that must be skipped by doxygen */
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
around the blocks that should be hidden and put:
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
in the config file then all blocks should be skipped by doxygen as long
|
|
Packit Service |
50c9f2 |
as \ref cfg_enable_preprocessing "ENABLE_PREPROCESSING" is set to `YES`.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_code_inc How can I change what is after the \#include in the class documentation?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
In most cases you can use \ref cfg_strip_from_inc_path "STRIP_FROM_INC_PATH"
|
|
Packit Service |
50c9f2 |
to strip a user defined part of a path.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
You can also document your class as follows
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
/*! \class MyClassName include.h path/include.h
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* Docs for MyClassName
|
|
Packit Service |
50c9f2 |
*/
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
To make doxygen put
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\#include \<path/include.h\>
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
in the documentation of the class MyClassName regardless of the name of the actual
|
|
Packit Service |
50c9f2 |
header file in which the definition of MyClassName is contained.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
If you want doxygen to show that the include file should be included using
|
|
Packit Service |
50c9f2 |
quotes instead of angle brackets you should type:
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
/*! \class MyClassName myhdr.h "path/myhdr.h"
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* Docs for MyClassName
|
|
Packit Service |
50c9f2 |
*/
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_chm How can I use tag files in combination with compressed HTML?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
If you want to refer from one compressed HTML file
|
|
Packit Service |
50c9f2 |
\c a.chm to another compressed HTML file
|
|
Packit Service |
50c9f2 |
called \c b.chm, the
|
|
Packit Service |
50c9f2 |
link in \c a.chm must have the following format:
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
Unfortunately this only works if both compressed HTML files are in the same
|
|
Packit Service |
50c9f2 |
directory.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
As a result you must rename the generated \c index.chm files for all projects
|
|
Packit Service |
50c9f2 |
into something unique and put all .chm files in one directory.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Suppose you have a project \e a referring to a project \e b using tag file
|
|
Packit Service |
50c9f2 |
\c b.tag, then you could rename the \c index.chm for project \e a into
|
|
Packit Service |
50c9f2 |
\c a.chm and the \c index.chm for project \e b into \c b.chm. In the
|
|
Packit Service |
50c9f2 |
configuration file for project \e a you write:
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
TAGFILES = b.tag=b.chm::
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_html I don't like the quick index that is put above each HTML page, what do I do?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
You can disable the index by setting \ref cfg_disable_index "DISABLE_INDEX" to `YES`. Then you can
|
|
Packit Service |
50c9f2 |
put in your own header file by writing your own header and feed that to
|
|
Packit Service |
50c9f2 |
\ref cfg_html_header "HTML_HEADER".
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_html_header The overall HTML output looks different, while I only wanted to use my own html header file
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
You probably forgot to include the stylesheet doxygen.css that
|
|
Packit Service |
50c9f2 |
doxygen generates. You can include this by putting
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
<LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css">
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
in the HEAD section of the HTML page.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_use_qt Why does doxygen use Qt?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The most important reason is to have a platform abstraction for most
|
|
Packit Service |
50c9f2 |
Unices and Windows by means of the QFile, QFileInfo, QDir, QDate,
|
|
Packit Service |
50c9f2 |
QTime and QIODevice classes.
|
|
Packit Service |
50c9f2 |
Another reason is for the nice and bug free utility classes, like QList,
|
|
Packit Service |
50c9f2 |
QDict, QString, QArray, QTextStream, QRegExp, QXML etc.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The GUI front-end doxywizard uses Qt for... well... the GUI!
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_excl_dir How can I exclude all test directories from my directory tree?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Simply put an exclude pattern like this in the configuration file:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
EXCLUDE_PATTERNS = */test/*
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_class Doxygen automatically generates a link to the class MyClass somewhere in the running text. How do I prevent that at a certain place?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Put a \% in front of the class name. Like this: \%MyClass. Doxygen will then
|
|
Packit Service |
50c9f2 |
remove the % and keep the word unlinked.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_pgm_X My favorite programming language is X. Can I still use doxygen?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
No, not as such; doxygen needs to understand the structure of what it reads.
|
|
Packit Service |
50c9f2 |
If you don't mind spending some time on it, there are several options:
|
|
Packit Service |
50c9f2 |
- If the grammar of X is close to C or C++, then it is probably not too hard to
|
|
Packit Service |
50c9f2 |
tweak src/scanner.l a bit so the language is supported. This is done
|
|
Packit Service |
50c9f2 |
for all other languages directly supported by doxygen
|
|
Packit Service |
50c9f2 |
(i.e. Java, IDL, C#, PHP).
|
|
Packit Service |
50c9f2 |
- If the grammar of X is somewhat different than you can write an input
|
|
Packit Service |
50c9f2 |
filter that translates X into something similar enough to C/C++ for
|
|
Packit Service |
50c9f2 |
doxygen to understand (this approach is taken for VB, Object Pascal, and
|
|
Packit Service |
50c9f2 |
Javascript, see http://www.stack.nl/~dimitri/doxygen/download.html#helpers).
|
|
Packit Service |
50c9f2 |
- If the grammar is completely different one could write a parser for X and
|
|
Packit Service |
50c9f2 |
write a backend that produces a similar syntax tree as is done by
|
|
Packit Service |
50c9f2 |
src/scanner.l (and also by src/tagreader.cpp while reading tag files).
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_lex Help! I get the cryptic message "input buffer overflow, can't enlarge buffer because scanner uses REJECT"
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
This error happens when doxygen's lexical scanner has a rule that matches
|
|
Packit Service |
50c9f2 |
more than 256K of input characters in one go. I've seen this happening
|
|
Packit Service |
50c9f2 |
on a very large generated file (\>256K lines), where the built-in preprocessor
|
|
Packit Service |
50c9f2 |
converted it into an empty file (with \>256K of newlines). Another case
|
|
Packit Service |
50c9f2 |
where this might happen is if you have lines in your code with more than
|
|
Packit Service |
50c9f2 |
256K characters.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
If you have run into such a case and want me to fix it, you
|
|
Packit Service |
50c9f2 |
should send me a code fragment that triggers the message. To work around
|
|
Packit Service |
50c9f2 |
the problem, put some line-breaks into your file, split it up into smaller
|
|
Packit Service |
50c9f2 |
parts, or exclude it from the input using EXCLUDE.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_latex When running make in the latex dir I get "TeX capacity exceeded". Now what?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
You can edit the texmf.cfg file to increase the default values of the
|
|
Packit Service |
50c9f2 |
various buffers and then run "texconfig init".
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_stl Why are dependencies via STL classes not shown in the dot graphs?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen is unaware of the STL classes, unless the
|
|
Packit Service |
50c9f2 |
option \ref cfg_builtin_stl_support "BUILTIN_STL_SUPPORT" is turned on.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_search I have problems getting the search engine to work with PHP5 and/or windows
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Please read this for hints on where to look.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_cmdline Can I configure doxygen from the command line?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Not via command line options, but doxygen can read from stdin ,
|
|
Packit Service |
50c9f2 |
so you can pipe things through it. Here's an example how to override an option
|
|
Packit Service |
50c9f2 |
in a configuration file from the command line (assuming a UNIX like environment):
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
( cat Doxyfile ; echo "PROJECT_NUMBER=1.0" ) | doxygen -
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
For Windows the following would do the same:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
( type Doxyfile & echo PROJECT_NUMBER=1.0 ) | doxygen.exe -
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
If multiple options with the same name are specified then doxygen will use
|
|
Packit Service |
50c9f2 |
the last one. To append to an existing option you can use the += operator.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_name How did doxygen get its name?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen got its name from playing with the words
|
|
Packit Service |
50c9f2 |
documentation and generator.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
documentation -> docs -> dox
|
|
Packit Service |
50c9f2 |
generator -> gen
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
At the time I was looking into \c lex and \c yacc, where a lot of things start with
|
|
Packit Service |
50c9f2 |
"yy", so the "y" slipped in and made things pronounceable
|
|
Packit Service |
50c9f2 |
(the proper pronouncement is Docs-ee-gen, so with a long "e").
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section faq_why What was the reason to develop doxygen?
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
I once wrote a GUI widget based on the Qt library (it is still available at
|
|
Packit Service |
50c9f2 |
https://sourceforge.net/projects/qdbttabular/ but hasn't been updated since 2002).
|
|
Packit Service |
50c9f2 |
Qt had nicely generated documentation (using an internal tool which
|
|
Packit Service |
50c9f2 |
they didn't want to release)
|
|
Packit Service |
50c9f2 |
and I wrote similar docs by hand.
|
|
Packit Service |
50c9f2 |
This was a nightmare to maintain, so I wanted a similar tool. I looked at
|
|
Packit Service |
50c9f2 |
Doc++ but that just wasn't good enough (it didn't support signals and
|
|
Packit Service |
50c9f2 |
slots and did not have the Qt look and feel I had grown to like),
|
|
Packit Service |
50c9f2 |
so I started to write my own tool...
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\htmlonly
|
|
Packit Service |
50c9f2 |
Go to the next section or return to the
|
|
Packit Service |
50c9f2 |
index.
|
|
Packit Service |
50c9f2 |
\endhtmlonly
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
*/
|
|
Packit Service |
50c9f2 |
|