author Peter Kovacs Mon, 26 May 2008 13:31:41 +0200 changeset 160 b1bd0c2a7f57 parent 158 500f3cbff9e4 child 161 2c999941b871
Improved documentation for counters
 lemon/counter.h file | annotate | diff | comparison | revisions
     1.1 --- a/lemon/counter.h	Sun May 25 17:01:11 2008 +0200
1.2 +++ b/lemon/counter.h	Mon May 26 13:31:41 2008 +0200
1.3 @@ -96,38 +96,97 @@
1.5    /// @{
1.6
1.7 -  ///A counter class
1.8 +  /// A counter class
1.9
1.10 -  ///This class makes it easier to count certain events. You can increment
1.11 -  ///or decrement the counter using operator++ and operator--.
1.12 -  ///A report is automatically printed on destruction.
1.13 -  ///\todo More doc
1.14 +  /// This class makes it easier to count certain events (e.g. for debug
1.15 +  /// reasons).
1.16 +  /// You can increment or decrement the counter using \c operator++,
1.17 +  /// \c operator--, \c operator+= and \c operator-=. You can also
1.18 +  /// define subcounters for the different phases of the algorithm or
1.19 +  /// for different types of operations.
1.20 +  /// A report containing the given title and the value of the counter
1.21 +  /// is automatically printed on destruction.
1.22 +  ///
1.23 +  /// The following example shows the usage of counters and subcounters.
1.24 +  /// \code
1.25 +  /// // Bubble sort
1.26 +  /// std::vector<T> v;
1.27 +  /// ...
1.28 +  /// Counter op("Operations: ");
1.29 +  /// Counter::SubCounter as(op, "Assignments: ");
1.30 +  /// Counter::SubCounter co(op, "Comparisons: ");
1.31 +  /// for (int i = v.size()-1; i > 0; --i) {
1.32 +  ///   for (int j = 0; j < i; ++j) {
1.33 +  ///     if (v[j] > v[j+1]) {
1.34 +  ///       T tmp = v[j];
1.35 +  ///       v[j] = v[j+1];
1.36 +  ///       v[j+1] = tmp;
1.37 +  ///       as += 3;          // three assignments
1.38 +  ///     }
1.39 +  ///     ++co;               // one comparison
1.40 +  ///   }
1.41 +  /// }
1.42 +  /// \endcode
1.43 +  ///
1.44 +  /// This code prints out something like that:
1.45 +  /// \code
1.46 +  /// Comparisons: 45
1.47 +  /// Assignments: 57
1.48 +  /// Operations: 102
1.49 +  /// \endcode
1.50 +  ///
1.51 +  /// \sa NoCounter
1.52    class Counter
1.53    {
1.54      std::string _title;
1.55      std::ostream &_os;
1.56      int count;
1.57    public:
1.58 -    ///\e
1.59
1.61 +    /// SubCounter class
1.62 +
1.63 +    /// This class can be used to setup subcounters for a \ref Counter
1.64 +    /// to have finer reports. A subcounter provides exactly the same
1.65 +    /// operations as the main \ref Counter, but it also increments and
1.66 +    /// decrements the value of its parent.
1.67 +    /// Subcounters can also have subcounters.
1.68 +    ///
1.69 +    /// The parent counter must be given as the first parameter of the
1.70 +    /// constructor. Apart from that a title and an \c ostream object
1.71 +    /// can also be given just like for the main \ref Counter.
1.72      ///
1.73 +    /// A report containing the given title and the value of the
1.74 +    /// subcounter is automatically printed on destruction. If you
1.75 +    /// would like to turn off this report, use \ref NoSubCounter
1.77 +    ///
1.78 +    /// \sa NoSubCounter
1.79      typedef _SubCounter<Counter> SubCounter;
1.80 -    ///\e
1.81
1.83 +    /// SubCounter class without printing report on destruction
1.84 +
1.85 +    /// This class can be used to setup subcounters for a \ref Counter.
1.86 +    /// It is the same as \ref SubCounter but it does not print report
1.87 +    /// on destruction. (It modifies the value of its parent, so 'No'
1.88 +    /// only means 'do not print'.)
1.89      ///
1.90 +    /// Replacing \ref SubCounter "SubCounter"s with \ref NoSubCounter
1.91 +    /// "NoSubCounter"s makes it possible to turn off reporting
1.92 +    /// subcounter values without actually removing the definitions
1.93 +    /// and the increment or decrement operators.
1.94 +    ///
1.95 +    /// \sa SubCounter
1.96      typedef _NoSubCounter<Counter> NoSubCounter;
1.97
1.98 -    ///\e
1.99 +    /// Constructor.
1.100      Counter() : _title(), _os(std::cerr), count(0) {}
1.101 -    ///\e
1.102 +    /// Constructor.
1.103      Counter(std::string title,std::ostream &os=std::cerr)
1.104        : _title(title), _os(os), count(0) {}
1.105 -    ///\e
1.106 +    /// Constructor.
1.107      Counter(const char *title,std::ostream &os=std::cerr)
1.108        : _title(title), _os(os), count(0) {}
1.109 -    ///Destructor. Prints the given title and the value of the counter.
1.110 +    /// Destructor. Prints the given title and the value of the counter.
1.111      ~Counter() {
1.112        _os << _title << count <<std::endl;
1.113      }
1.114 @@ -143,16 +202,23 @@
1.115      Counter &operator+=(int c) { count+=c; return *this;}
1.116      ///\e
1.117      Counter &operator-=(int c) { count-=c; return *this;}
1.118 -    ///\e
1.119 +    /// Resets the counter to the given value.
1.120      void reset(int c=0) {count=c;}
1.121 -    ///\e
1.122 +    /// Returns the value of the counter.
1.123      operator int() {return count;}
1.124    };
1.125
1.126 -  ///'Do nothing' version of \ref Counter
1.127 +  /// 'Do nothing' version of Counter.
1.128
1.129 -  ///'Do nothing' version of \ref Counter.
1.130 -  ///\sa Counter
1.131 +  /// This class can be used in the same way as \ref Counter however it
1.132 +  /// does not count at all and does not print report on destruction.
1.133 +  ///
1.134 +  /// Replacing a \ref Counter with a \ref NoCounter makes it possible
1.135 +  /// to turn off all counting and reporting (SubCounters should also
1.136 +  /// be replaced with NoSubCounters), so it does not affect the
1.137 +  /// efficiency of the program at all.
1.138 +  ///
1.139 +  /// \sa Counter
1.140    class NoCounter
1.141    {
1.142    public: