documentation improvements

[[Imported from SVN: r983]]

common/debugstream.hh

@@ -8,7 +8,7 @@
 #include <iostream>
 #include <stack>
 
-#include "exceptions.hh"
+#include <dune/common/exceptions.hh>
 
 namespace Dune {
 
@@ -22,6 +22,7 @@ namespace Dune {
    */
 
   /*! \defgroup DebugOut Debug output
+     \ingroup Common
 
      The debug output is implemented by instaces of DebugStream which
      provides the following features:

common/dlist.hh

@@ -5,8 +5,17 @@
 
 namespace Dune {
 
-  /** \brief A doubly-linked list
+  /*! \addtogroup Common
+     @{
    */
+
+  /*! \file
+
+     Declaration of a doubly linked list
+   */
+
+
+  /*! A doubly-linked list */
   template <class T>
   class DoubleLinkedList {
   private:
@@ -21,13 +30,13 @@ namespace Dune {
       Element* p;
     public:
 
-      //! ???
+      //! constructor
       Iterator();
 
-      //! ???
+      //! comparison
       bool operator!= (Iterator x);
 
-      //! ???
+      //! comparison
       bool operator== (Iterator x);
 
       //! Prefix increment
@@ -42,51 +51,50 @@ namespace Dune {
       //! Postfix decrement
       Iterator operator-- (int);
 
-      //! ???
+      //! dereferenciation
       T& operator* () const;
 
-      //! ???
-      T* operator-> () const;     // Stroustrup p. 289
+      //! dereferenciation (Stroustrup p. 289)
+      T* operator-> () const;
 
-      //! ???
       friend class DoubleLinkedList<T>;
     } ;
 
-    //! ???
+    //! iterator at the lists start
     Iterator begin () const;
 
-    //! ???
+    //! iterator behind last element
     Iterator end () const;
 
-    //! ???
+    //! iterator at the lists end
     Iterator rbegin () const;
 
-    //! ???
+    //! iterator before the lists start
     Iterator rend () const;
 
 
-    //! ???
+    //! empty constructor
     DoubleLinkedList();
 
-    //! ???
+    //! copy constructor
     DoubleLinkedList (const DoubleLinkedList<T>&);
 
-    //! ???
+    //! destructor
     ~DoubleLinkedList();
 
-    //! ???
+    //!
     DoubleLinkedList<T>& operator= (const DoubleLinkedList<T>&);
 
-    //! ???
+    //! current list size
     int size () const;
 
-    //! ???
+    //! insert after an iterators position
     Iterator insert_after (Iterator i, T& t);
 
-    //! ???
+    //! insert befor an iterators position
     Iterator insert_before (Iterator i, T& t);
 
-    //! ???
+    //! remove selected element
     void erase (Iterator i);
 
   private:
@@ -104,6 +112,8 @@ namespace Dune {
 
 }
 
+//! }@
+
 #include "dlist.cc"
 
 #endif

common/stack.hh

 // -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 // vi: set et ts=4 sw=2 sts=2:
-#ifndef __DUNE_STACK_HH__
-#define __DUNE_STACK_HH__
+#ifndef DUNE_STACK_HH
+#define DUNE_STACK_HH
 
 #include <dune/common/dlist.hh>
 #include <dune/common/exceptions.hh>
 
 namespace Dune {
 
+  /*! \addtogroup Common
+     @{
+   */
+
+  /*! \file
+
+     This file implements two stack-classes Stack and FiniteStack. They are
+     mainly used by the grid iterators where exact knowledge of the stack
+     implementation is needed to guarantee efficient execution
+   */
+
   //! Exception thrown by the stack
   class StackException : public Exception {};
 
-  /** \brief A dynamic stack
+  /** dynamic stack implemented with a double linked list
+
+     This class can be used instead of the standard STL-stack if
+     detailed knowledge about the stacks implementation is needed. For
+     example, it is unknown if a copy of an empty STL-stack requires
+     time or not
+
+     \todo change interface to be STL-conforming
    */
   template<class T>
   class Stack : private DoubleLinkedList<T> {
@@ -86,8 +104,11 @@ namespace Dune {
 
 
   /** \brief A stack with static memory allocation
-   *
-   * \tparam n Maximum number of stack entries
+
+     This class implements a very efficient stack where the maximum
+     depth is known in advance
+
+     \tparam n Maximum number of stack entries
    */
   template<class T, int n>
   class FiniteStack {
@@ -142,4 +163,6 @@ namespace Dune {
 
 }
 
+//! @}
+
 #endif

common/timer.hh

@@ -16,21 +16,29 @@
 
 #include "exceptions.hh"
 
+namespace Dune {
 
-/*! \file
-    A simple timing class.
- */
+  /** @addtogroup Common
+     @{
+   */
 
-namespace Dune {
+  /*! \file
+      A simple timing class.
+   */
 
   class TimerError : public SystemError {} ;
 
-  /** @addtogroup common
-     @{
-   */
 
-  //! a simple stop watch
-  //! using the C command getrusage
+  /*! a simple stop watch
+
+     this class reports the elapsed user-time, i.e. time spent computing,
+     after the last call to Timer::reset(). The results are seconds and
+     fractional seconds. Note that the resolution of the timing depends
+     on your OS kernel which should be somewhere in the milisecond range.
+
+     The class is basically a wrapper for the libc-function getrusage()
+
+   */
   class Timer
   {
   public:
@@ -49,7 +57,7 @@ namespace Dune {
       cstart = ru.ru_utime;
     }
 
-    //! get elapsed user+sys time in seconds
+    //! get elapsed user-time in seconds
     double elapsed () const throw (TimerError)
     {
       rusage ru;