...tips for doxygen usage...

...feel free to add more tips :-)

[[Imported from SVN: r3165]]

doc/doxygen/.gitignore

 .deps
 doxy-header.html
+bestpractice.html
 doxygen-tag
 doxygen.log
 html

doc/doxygen/Makefile.am

@@ -5,7 +5,7 @@ EXTRA_DIST = Doxyfile Doxydep \
   doxy-footer.html doxy-header.html dune-doxy.css mainpage
 
 if BUILD_DOCS
-  WHAT = doxy-header.html doxygen-tag
+  WHAT = bestpractice.html doxy-header.html doxygen-tag
 endif
 
 all: $(WHAT)

doc/doxygen/bestpractice.wml

+# -*- html -*-
+# $Id$
+
+#use wml::layout::default title="DUNE - Doxygen Best Practice"
+#use wml::std::grid
+
+<h1> Doxygen Best Practice </h1>
+
+<h2> Overview </h2>
+<p>usefull tips when documenting your code</p>
+<ul>
+<li><a href="#copydoc">\copydoc</a></li>
+<li><a href="#ordermodules">Ordering Modules</a></li>
+</ul>
+
+<h2> usefull tips when documenting your code </h2>
+
+<h3><a id="copydoc">\copydoc &lt;link-object&gt;</a></h3>
+
+<p>
+<em>
+Use \copydoc in your derived class to reuse the documentation from the
+interface class.</em>
+</p>
+
+<p>
+Copies a documentation block from the object
+specified by &lt;link-object&gt; and pastes it at the location of the
+command. This command can be useful to avoid cases where a
+documentation block would otherwise have to be duplicated or it can be
+used to extend the documentation of an inherited member.
+</p>
+
+<p>
+The link object can point to a member (of a class, file or group), a
+class, a namespace, a group, a page, or a file (checked in that
+order). Note that if the object pointed to is a member (function,
+variable, typedef, etc), the compound (class, file, or group)
+containing it should also be documented for the copying to work.
+</p>
+
+<p>
+To copy the documentation for a member of a class for instance one can
+put the following in the documentation
+</p>
+
+<h3><a id="ordermodules">Ordering Modules</a></h3>
+
+<p><em>Use the file <tt>doxygen/modules</tt> to change the ordering of modules
+on the modules page</em></p>
+
+<p>Doxygen sorts the modules in the order it finds their
+definition. This is influenced by the order doxygen reads the
+source files and by the include statements in these source files.</p>
+
+<p>The <tt>modules</tt> file is read right after the mainpage, before any
+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

doc/index.wml

@@ -25,6 +25,7 @@ with <a href="http://www.doxygen.org/">Doxygen</a>)</li>
 
 <ul>
 <li><a href="devel/codingstyle.html">Coding Style</a></li>
+<li><a href="doxygen/bestpractice.html">Best Practice for Doxygen</a></li>
 <li><a href="devel/ugreader.html">Howto write
 	  file readers for the UGGrid</a></li>
 <li><a href="buildsystem.html">Understanding the build system</a>