[Lemon-commits] Peter Kovacs: Improved documentation for counters
Lemon HG
hg at lemon.cs.elte.hu
Mon May 26 14:51:33 CEST 2008
details: http://lemon.cs.elte.hu/hg/lemon/rev/b1bd0c2a7f57
changeset: 160:b1bd0c2a7f57
user: Peter Kovacs <kpeter [at] inf.elte.hu>
date: Mon May 26 13:31:41 2008 +0200
description:
Improved documentation for counters
diffstat:
1 file changed, 84 insertions(+), 18 deletions(-)
lemon/counter.h | 102 +++++++++++++++++++++++++++++++++++++++++++++----------
diffs (143 lines):
diff -r 500f3cbff9e4 -r b1bd0c2a7f57 lemon/counter.h
--- a/lemon/counter.h Sun May 25 17:01:11 2008 +0200
+++ b/lemon/counter.h Mon May 26 13:31:41 2008 +0200
@@ -96,38 +96,97 @@
/// \addtogroup timecount
/// @{
- ///A counter class
+ /// A counter class
- ///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
+ /// This class makes it easier to count certain events (e.g. for debug
+ /// reasons).
+ /// You can increment or decrement the counter using \c operator++,
+ /// \c operator--, \c operator+= and \c operator-=. You can also
+ /// define subcounters for the different phases of the algorithm or
+ /// for different types of operations.
+ /// A report containing the given title and the value of the counter
+ /// is automatically printed on destruction.
+ ///
+ /// The following example shows the usage of counters and subcounters.
+ /// \code
+ /// // Bubble sort
+ /// std::vector<T> v;
+ /// ...
+ /// Counter op("Operations: ");
+ /// Counter::SubCounter as(op, "Assignments: ");
+ /// Counter::SubCounter co(op, "Comparisons: ");
+ /// for (int i = v.size()-1; i > 0; --i) {
+ /// for (int j = 0; j < i; ++j) {
+ /// if (v[j] > v[j+1]) {
+ /// T tmp = v[j];
+ /// v[j] = v[j+1];
+ /// v[j+1] = tmp;
+ /// as += 3; // three assignments
+ /// }
+ /// ++co; // one comparison
+ /// }
+ /// }
+ /// \endcode
+ ///
+ /// This code prints out something like that:
+ /// \code
+ /// Comparisons: 45
+ /// Assignments: 57
+ /// Operations: 102
+ /// \endcode
+ ///
+ /// \sa NoCounter
class Counter
{
std::string _title;
std::ostream &_os;
int count;
public:
- ///\e
- ///\todo document please.
+ /// SubCounter class
+
+ /// This class can be used to setup subcounters for a \ref Counter
+ /// to have finer reports. A subcounter provides exactly the same
+ /// operations as the main \ref Counter, but it also increments and
+ /// decrements the value of its parent.
+ /// Subcounters can also have subcounters.
+ ///
+ /// The parent counter must be given as the first parameter of the
+ /// constructor. Apart from that a title and an \c ostream object
+ /// can also be given just like for the main \ref Counter.
///
+ /// A report containing the given title and the value of the
+ /// subcounter is automatically printed on destruction. If you
+ /// would like to turn off this report, use \ref NoSubCounter
+ /// instead.
+ ///
+ /// \sa NoSubCounter
typedef _SubCounter<Counter> SubCounter;
- ///\e
- ///\todo document please.
+ /// SubCounter class without printing report on destruction
+
+ /// This class can be used to setup subcounters for a \ref Counter.
+ /// It is the same as \ref SubCounter but it does not print report
+ /// on destruction. (It modifies the value of its parent, so 'No'
+ /// only means 'do not print'.)
///
+ /// Replacing \ref SubCounter "SubCounter"s with \ref NoSubCounter
+ /// "NoSubCounter"s makes it possible to turn off reporting
+ /// subcounter values without actually removing the definitions
+ /// and the increment or decrement operators.
+ ///
+ /// \sa SubCounter
typedef _NoSubCounter<Counter> NoSubCounter;
- ///\e
+ /// Constructor.
Counter() : _title(), _os(std::cerr), count(0) {}
- ///\e
+ /// Constructor.
Counter(std::string title,std::ostream &os=std::cerr)
: _title(title), _os(os), count(0) {}
- ///\e
+ /// Constructor.
Counter(const char *title,std::ostream &os=std::cerr)
: _title(title), _os(os), count(0) {}
- ///Destructor. Prints the given title and the value of the counter.
+ /// Destructor. Prints the given title and the value of the counter.
~Counter() {
_os << _title << count <<std::endl;
}
@@ -143,16 +202,23 @@
Counter &operator+=(int c) { count+=c; return *this;}
///\e
Counter &operator-=(int c) { count-=c; return *this;}
- ///\e
+ /// Resets the counter to the given value.
void reset(int c=0) {count=c;}
- ///\e
+ /// Returns the value of the counter.
operator int() {return count;}
};
- ///'Do nothing' version of \ref Counter
+ /// 'Do nothing' version of Counter.
- ///'Do nothing' version of \ref Counter.
- ///\sa Counter
+ /// This class can be used in the same way as \ref Counter however it
+ /// does not count at all and does not print report on destruction.
+ ///
+ /// Replacing a \ref Counter with a \ref NoCounter makes it possible
+ /// to turn off all counting and reporting (SubCounters should also
+ /// be replaced with NoSubCounters), so it does not affect the
+ /// efficiency of the program at all.
+ ///
+ /// \sa Counter
class NoCounter
{
public:
More information about the Lemon-commits
mailing list