mods for doxygen-0.49-990728

1 files changed, 117 insertions, 1 deletions

diff --git a/doc/starting.doc b/doc/starting.doc
index 1d3cbcd..78f9309 100644
--- a/doc/starting.doc
+++ b/doc/starting.doc
@@ -397,6 +397,122 @@ from typos in formulas. It may have to be necessary to remove the
 file formula.repository that is written in the html directory to 
 a rid of an incorrect formula
 
+\subsection preprocessing Preprocessing
+
+Source files that are used as input to doxygen can be parsed by doxygen's
+build-in C-preprocessor.
+
+By default doxygen does only partial preprocessing. That is, it 
+evaluates conditional compilation statements (like \#if) and 
+evaluates macro definitions, but is does not perform macro expansion.
+
+So if you have the following code fragment
+\verbatim
+#define VERSION 200
+#define CONST_STRING const char *
+
+#if VERSION >= 200
+  static CONST_STRING version = "2.xx";
+#else
+  static CONST_STRING version = "1.xx";
+#endif
+\endverbatim
+
+Then by default doxygen will feed the following to its parser:
+
+\verbatim
+#define VERSION
+#define CONST_STRING
+
+  static CONST_STRING version = "1.xx";
+\endverbatim
+
+You can disable all preprocessing by setting \c ENABLE_PREPROCESSING to \c 
+NO in the configuation file. In the case above doxygen will then read
+both statements!
+
+In case you want to expand the \c CONST_STRING macro, you should set the
+\c MACRO_EXPANSION tag in the config file to \c YES. Then the result 
+after preprocessing becomes:
+
+\verbatim
+#define VERSION
+#define CONST_STRING
+
+  static const char * version = "1.xx";
+\endverbatim
+
+Notice that doxygen will now expand \e all macro definitions 
+(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.  
+
+As an example, suppose you have the following obfusciated code fragment
+of an abstract base class called \c IUnknown:
+
+\verbatim
+/*! A reference to an IID */
+#ifdef __cplusplus
+#define REFIID const IID &
+#else
+#define REFIID const IID *
+#endif
+
+/*! 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;
+};
+\endverbatim
+
+without macro expansion doxygen will get confused, but we may not want to 
+expand the REFIID macro, because it is documented and the user that reads 
+the documentation should use it when implementing the interface.
+
+By setting the following in the config file:
+
+\verbatim
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION      = YES
+EXPAND_ONLY_PREDEF   = YES
+PREDEFINED           = "DECLARE_INTERFACE(name)=class name" \
+                       "MEMBER(result,name)=virtual result name" \
+                       "PURE= = 0" \
+                       THIS_= \
+                       THIS= \
+		       __cplusplus
+\endverbatim
+
+we can make sure that the proper result is fed to doxygen's parser:
+\verbatim
+/*! A reference to an IID */
+#define REFIID
+
+/*! The IUnknown interface */
+class  IUnknown
+{
+  virtual  HRESULT   QueryInterface ( REFIID iid, void **ppv) = 0;
+  virtual  ULONG   AddRef () = 0;
+  virtual  ULONG   Release () = 0;
+};
+\endverbatim
+
+Notice that the \c PREDEFINED tag accepts function like macro definitions
+(like \c DECLARE_INTERFACE), normal macro substitutions (like \c PURE
+and \c THIS) and plain defines (like \c __cplusplus).
+
+Notice also that preprocessor definitions that are normally defined 
+automatically by the preprocessor (like \c __cplusplus), have to be defined 
+by hand with doxygen's parser (this is done because these defines
+are often platform/compiler specific).
+
+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.
+
 \subsection moreinfo More information
 
 \addindex QdbtTabular
@@ -405,7 +521,7 @@ the documentation of QdbtTabular</a> \latexonly
 ({\tt http://www.stack.nl/$\sim$dimitri/qdbttabular/html})\endlatexonly.
 \htmlonly
 I hope that was clear. If not, please let me know, so I can improve this document. If you have problems 
-take a look at the <a href="trouble.html">troubleshooting</a> section. 
+take a look at the <a href="faq.html">faq</a> and the <a href="trouble.html">troubleshooting</a> sections. 
 \endhtmlonly
 
 */