# HG changeset patch
# User alpar
# Date 1133894666 0
# Node ID 78b5ea23f0f1f91cda22dc4c78887960aef9ae58
# Parent  50d1d6acfcc24ff9ee0d93437d7a854d05891d69
Doc improvements

diff -r 50d1d6acfcc2 -r 78b5ea23f0f1 lemon/counter.h
--- a/lemon/counter.h	Tue Dec 06 11:59:44 2005 +0000
+++ b/lemon/counter.h	Tue Dec 06 18:44:26 2005 +0000
@@ -95,6 +95,7 @@
   ///This class makes it easier to count certain events. You can increment
   ///or decrement the counter using operator++ and operator--.
   ///A report is automatically printed on destruction.
+  ///\todo More doc
   class Counter 
   {
     std::string _title;
diff -r 50d1d6acfcc2 -r 78b5ea23f0f1 lemon/time_measure.h
--- a/lemon/time_measure.h	Tue Dec 06 11:59:44 2005 +0000
+++ b/lemon/time_measure.h	Tue Dec 06 18:44:26 2005 +0000
@@ -44,7 +44,8 @@
   /// TimeStamp's can be added to or substracted from each other and
   /// they can be pushed to a stream.
   ///
-  /// In most cases, perhaps \ref Timer class is what you want to use instead.
+  /// In most cases, perhaps the \ref Timer or the \ref TimeReport
+  /// class is what you want to use instead.
   ///
   ///\author Alpar Juttner
 
@@ -193,6 +194,30 @@
     return t*b;
   }
   
+  ///Prints the time counters
+
+  ///Prints the time counters in the following form:
+  ///
+  /// <tt>u: XX.XXs s: XX.XXs cu: XX.XXs cs: XX.XXs real: XX.XXs</tt>
+  ///
+  /// where the values are the
+  /// \li \c u: user cpu time,
+  /// \li \c s: system cpu time,
+  /// \li \c cu: user cpu time of children,
+  /// \li \c cs: system cpu time of children,
+  /// \li \c real: real time.
+  /// \relates TimeStamp
+  inline std::ostream& operator<<(std::ostream& os,const TimeStamp &t)
+  {
+    long cls = sysconf(_SC_CLK_TCK);
+    os << "u: " << double(t.getTms().tms_utime)/cls <<
+      "s, s: " << double(t.getTms().tms_stime)/cls <<
+      "s, cu: " << double(t.getTms().tms_cutime)/cls <<
+      "s, cs: " << double(t.getTms().tms_cstime)/cls <<
+      "s, real: " << t.realTime() << "s";
+    return os;
+  }
+
   ///Class for measuring the cpu time and real time usage of the process
 
   ///Class for measuring the cpu time and real time usage of the process.
@@ -229,12 +254,11 @@
   ///Also, if you start and stop the timer very frequently, it could lead
   ///distorted results.
   ///
-  ///The \ref Timer also counts the number of \ref start()
-  ///executions, and is stops only after the same amount (or more)
-  ///\ref stop() "stop()"s. This can be useful e.g. to compute the running time
-  ///of recursive functions.
+  ///\note If you want to measure the running time of the execution of a certain
+  ///function, consider the usage of \ref TimeReport instead.
   ///
   ///\todo This shouldn't be Unix (Linux) specific.
+  ///\sa TimeReport
   ///
   ///\author Alpar Juttner
   class Timer
@@ -252,16 +276,16 @@
     ///
     Timer(bool run=true) :_running(run) {_reset();}
 
-    ///Computes the ellapsed time
+    ///\name Control the state of the timer
+    ///Basically a Timer can be either running or stopped,
+    ///but it provides a bit finer control on the execution.
+    ///The \ref Timer also counts the number of \ref start()
+    ///executions, and is stops only after the same amount (or more)
+    ///\ref stop() "stop()"s. This can be useful e.g. to compute the running time
+    ///of recursive functions.
+    ///
 
-    ///This conversion computes the ellapsed time
-    ///
-    operator TimeStamp () const
-    {
-      TimeStamp t;
-      t.stamp();
-      return _running?t-start_time:start_time;
-    }
+    ///@{
 
     ///Reset and stop the time counters
 
@@ -352,6 +376,12 @@
       start();
     }
     
+    ///@}
+
+    ///\name Query Functions for the ellapsed time
+
+    ///@{
+
     ///Gives back the ellapsed user time of the process
     double userTime() const
     {
@@ -377,53 +407,87 @@
     {
       return operator TimeStamp().realTime();
     }
+    ///Computes the ellapsed time
 
+    ///This conversion computes the ellapsed time, therefore you can print
+    ///the ellapsed time like this.
+    ///\code
+    ///  Timer T;
+    ///  doSomething();
+    ///  std::cout << T << '\n';
+    ///\endcode
+    operator TimeStamp () const
+    {
+      TimeStamp t;
+      t.stamp();
+      return _running?t-start_time:start_time;
+    }
+
+
+    ///@}
   };
 
   ///Same as \ref Timer but prints a report on destruction.
 
   ///Same as \ref Timer but prints a report on destruction.
-  ///\todo Untested
+  ///This example shows its usage.
+  ///\code
+  ///  void myAlg(ListGraph &g,int n)
+  ///  {
+  ///    TimeReport TR("Running time of myAlg: ");
+  ///    ... //Here comes the algorithm
+  ///  }
+  ///\endcode
+  ///
+  ///\sa Timer
+  ///\sa NoTimeReport
+  ///\todo There is no test case for this
   class TimeReport : public Timer 
   {
     std::string _title;
     std::ostream &_os;
   public:
     ///\e
-    
-    TimeReport(std::string title,std::ostream &os,bool run) 
+
+    ///\param title This text will be printed before the ellapsed time.
+    ///\param os The stream to print the report to.
+    ///\param run Sets whether the timer should start immediately.
+
+    TimeReport(std::string title,std::ostream &os=std::cerr,bool run=true) 
       : Timer(run), _title(title), _os(os){}
+    ///\e Prints the ellapsed time on destruction.
     ~TimeReport() 
     {
-      _os << _title << this << std::endl;
+      _os << _title << *this << std::endl;
     }
   };
       
-  ///Prints the time counters
+  ///'Do nothing' version of \ref TimeReport
 
-  ///Prints the time counters in the following form:
+  ///\sa TimeReport
   ///
-  /// <tt>u: XX.XXs s: XX.XXs cu: XX.XXs cs: XX.XXs real: XX.XXs</tt>
-  ///
-  /// where the values are the
-  /// \li \c u: user cpu time,
-  /// \li \c s: system cpu time,
-  /// \li \c cu: user cpu time of children,
-  /// \li \c cs: system cpu time of children,
-  /// \li \c real: real time.
-  /// \relates TimeStamp
-  inline std::ostream& operator<<(std::ostream& os,const TimeStamp &t)
+  class NoTimeReport
   {
-    long cls = sysconf(_SC_CLK_TCK);
-    os << "u: " << double(t.getTms().tms_utime)/cls <<
-      "s, s: " << double(t.getTms().tms_stime)/cls <<
-      "s, cu: " << double(t.getTms().tms_cutime)/cls <<
-      "s, cs: " << double(t.getTms().tms_cstime)/cls <<
-      "s, real: " << t.realTime() << "s";
-    return os;
-  }
+  public:
+    ///\e
+    NoTimeReport(std::string title,std::ostream &os=std::cerr,bool run=true) {}
+    ///\e Do nothing.
+    ~NoTimeReport() {}
 
-  
+    operator TimeStamp () const { return TimeStamp(); }
+    void reset() {}
+    void start() {}
+    void stop() {}
+    void halt() {} 
+    int running() { return 0; }
+    void restart() {}
+    double userTime() const { return 0; }
+    double systemTime() const { return 0; }
+    double cUserTime() const { return 0; }
+    double cSystemTime() const { return 0; }
+    double realTime() const { return 0; }
+  };
+      
   ///Tool to measure the running time more exactly.
   
   ///This function calls \c f several times and returns the average