fix include statements in doxygen output, update bestpractice to tell

how it works

[[Imported from SVN: r5591]]

doc/doxygen/Doxyfile.in

@@ -124,7 +124,7 @@ STRIP_FROM_PATH        =
 # definition is used. Otherwise one should specify the include paths that 
 # are normally passed to the compiler using the -I flag.
 
-STRIP_FROM_INC_PATH    = 
+STRIP_FROM_INC_PATH    = @abs_top_srcdir@
 
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter 
 # (but less readable) file names. This can be useful is your file systems 
@@ -462,8 +462,8 @@ WARN_LOGFILE           =
 
 INPUT                  = @srcdir@/mainpage \
                          @srcdir@/modules \
-                         @top_srcdir@/common/modules \
-                         @top_srcdir@/common
+                         @top_srcdir@/dune/common/modules \
+                         @top_srcdir@/dune/common
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 

doc/doxygen/bestpractice.wml

@@ -15,6 +15,43 @@
 
 <h2> usefull tips when documenting your code </h2>
 
+<h3>correct #include statements</h3>
+
+<p>
+Doxygen tends to strip the while path from the include statements. In
+Dune we usually require include statements like
+<pre>
+  \#include &lt;dune/common/fvector.hh&gt;
+</pre>
+Doxygen will just write
+<pre>
+  \#include &lt;fvector.hh&gt;
+</pre>
+In order to trick/force Doxygen to write the correct include statement
+you have to adjust your Doxyfile.in as follows:
+</p>
+
+<ol>
+<li>
+<p>use <tt>@top_srcdir@/dune/...</tt> to point to the include
+  directories:
+</p>
+<pre>
+  INPUT                  = @srcdir@/mainpage \
+                         @srcdir@/modules \
+                         @top_srcdir@/dune/common/modules \
+                         @top_srcdir@/dune/common
+</pre>
+</li>
+<li>
+<p>set the <tt>STRIP_FROM_INC_PATH</tt> to point to your
+  abs_top_srcdir:</p>
+<pre>
+  STRIP_FROM_INC_PATH    = @abs_top_srcdir@
+</pre>
+</li>
+</ol>
+
 <h3>\copydoc &lt;link-object&gt;</h3>
 
 <p>
@@ -57,4 +94,4 @@ source files and by the include statements in these source files.</p>
 source files are parsed. Entering a <tt>@defgroup</tt> statement makes
 this module known to doxygen so that all modules mentioned in the
 <tt>modules</tt> file are listed first and in the order they are
-defined there.</p>
\ No newline at end of file
+defined there.</p>