From: Mikko Rasa <tdb@tdb.fi>
Date: Thu, 9 Jun 2011 08:43:22 +0000 (+0300)
Subject: Style and comment updates
X-Git-Url: http://git.tdb.fi/?a=commitdiff_plain;h=1f0843257065789231a9949e0a81b79afd7bbebe;p=libs%2Fcore.git

Style and comment updates
---

diff --git a/source/core/application.h b/source/core/application.h
index c7a1af1..08393b7 100644
--- a/source/core/application.h
+++ b/source/core/application.h
@@ -4,8 +4,7 @@
 namespace Msp {
 
 /**
-Base class for applications.  Inherit the main class from this and add a static
-member of type RegApp<MainClass>.
+Base class for applications.  See also RegisteredApplication.
 */
 class Application
 {
@@ -49,6 +48,10 @@ private:
 };
 
 
+/**
+Registers the class to be used for program startup.  The main application class
+should be derived from this.
+*/
 template<typename T>
 class RegisteredApplication: public Application
 {
diff --git a/source/core/getopt.h b/source/core/getopt.h
index bfa2ef2..56ab051 100644
--- a/source/core/getopt.h
+++ b/source/core/getopt.h
@@ -65,6 +65,9 @@ private:
 	template<typename T>
 	class Option: public OptBase
 	{
+	private:
+		T &data;
+
 	public:
 		Option(char s, const std::string &l, T &d, ArgType a): OptBase(s, l, a), data(d) { }
 
@@ -81,13 +84,14 @@ private:
 				throw usage_error("Invalid argument for --"+lng+" ("+e.what()+")");
 			}
 		}
-	private:
-		T &data;
 	};
 
 	template<typename T>
 	class ListOption: public OptBase
 	{
+	private:
+		T &data;
+
 	public:
 		ListOption(char s, const std::string &l, T &d, ArgType a): OptBase(s, l, a), data(d)
 		{ if(arg_type!=REQUIRED_ARG) throw std::invalid_argument("ListOption arg_type!=REQUIRED"); }
@@ -105,8 +109,6 @@ private:
 				throw usage_error("Invalid argument for --"+lng+" ("+e.what()+")");
 			}
 		}
-	private:
-		T &data;
 	};
 
 	bool help;
diff --git a/source/core/main.cpp b/source/core/main.cpp
index 84e0f42..19791ee 100644
--- a/source/core/main.cpp
+++ b/source/core/main.cpp
@@ -1,7 +1,6 @@
 #ifdef WIN32
 #include <windows.h>
 #endif
-
 #include "application.h"
 
 #ifdef WIN32
diff --git a/source/core/mutex.h b/source/core/mutex.h
index 18f9039..0fe9e82 100644
--- a/source/core/mutex.h
+++ b/source/core/mutex.h
@@ -35,21 +35,19 @@ public:
 };
 
 /**
-Locks the mutex for te lifetime of the object.
+Locks the mutex for the lifetime of the object.
 */
 class MutexLock
 {
 private:
 	Mutex &mutex;
 
+	MutexLock(const MutexLock &);
 public:
 	MutexLock(Mutex &m, bool l = true): mutex(m) { if(l) mutex.lock(); }
 	~MutexLock() { mutex.unlock(); }
 
 	void lock() { mutex.lock(); }
-private:
-	MutexLock(const MutexLock &);
-	MutexLock &operator=(const MutexLock &);
 };
 
 /**
@@ -59,15 +57,16 @@ exists, the mutex will stay locked.
 template<typename T>
 class MutexPtr
 {
+private:
+	RefPtr<MutexLock> mutex;
+	T *data;
+
 public:
 	MutexPtr(T *d, Mutex &m): mutex(new MutexLock(m)), data(d) { }
 
 	T &operator*() const { return *data; }
 	T *operator->() const { return data; }
-	void clear() { mutex=0; data = 0; }
-private:
-	RefPtr<MutexLock> mutex;
-	T *data;
+	void clear() { mutex = 0; data = 0; }
 };
 
 }
diff --git a/source/core/thread.cpp b/source/core/thread.cpp
index a8c80b6..cfc0c37 100644
--- a/source/core/thread.cpp
+++ b/source/core/thread.cpp
@@ -43,10 +43,6 @@ Thread::~Thread()
 	delete priv_;
 }
 
-/**
-Waits for the thread to exit.  Calling this from the thread will cause a
-deadlock.
-*/
 void Thread::join()
 {
 	if(!launched_)
@@ -60,9 +56,6 @@ void Thread::join()
 	launched_ = false;
 }
 
-/**
-Violently terminates the thread.
-*/
 void Thread::kill()
 {
 #ifdef WIN32
diff --git a/source/core/thread.h b/source/core/thread.h
index ac7169f..ae25707 100644
--- a/source/core/thread.h
+++ b/source/core/thread.h
@@ -26,7 +26,12 @@ private:
 public:
 	virtual ~Thread();
 
+	/** Waits for the thread to exit.  Calling this from the thread will cause a
+	deadlock. */
 	void join();
+
+	/** Violently terminates the thread.  This should only be used as a last
+	resort, as the thread gets no chance to clean up. */
 	void kill();
 protected:
 	void launch();
diff --git a/source/stringcodec/codec.h b/source/stringcodec/codec.h
index c70e052..e0e0a96 100644
--- a/source/stringcodec/codec.h
+++ b/source/stringcodec/codec.h
@@ -177,7 +177,7 @@ public:
 
 
 /** Convenience function that decodes a string. */
-template<class C>
+template<typename C>
 ustring decode(const std::string &s)
 {
 	typename C::Decoder dec;
@@ -185,7 +185,7 @@ ustring decode(const std::string &s)
 }
 
 /** Convenience function that encodes a string. */
-template<class C>
+template<typename C>
 std::string encode(const ustring &s)
 {
 	typename C::Encoder enc;
@@ -193,7 +193,7 @@ std::string encode(const ustring &s)
 }
 
 /** Convenience function that transcodes a string from one codec to another. */
-template<class F, class T>
+template<typename F, typename T>
 std::string transcode(const std::string &s)
 {
 	return encode<T>(decode<F>(s));
diff --git a/source/stringcodec/jisx0208.h b/source/stringcodec/jisx0208.h
index c59e44f..c8e6944 100644
--- a/source/stringcodec/jisx0208.h
+++ b/source/stringcodec/jisx0208.h
@@ -48,8 +48,8 @@ struct Kuten
 	operator bool() { return ku!=0 && ten!=0; }
 };
 
-extern unichar jisx0208_to_ucs(Kuten);
-extern Kuten ucs_to_jisx0208(unichar);
+unichar jisx0208_to_ucs(Kuten);
+Kuten ucs_to_jisx0208(unichar);
 
 } // namespace StringCodec
 } // namespace Msp
diff --git a/source/strings/format.cpp b/source/strings/format.cpp
index 4b5bcd0..1b8b465 100644
--- a/source/strings/format.cpp
+++ b/source/strings/format.cpp
@@ -11,10 +11,6 @@ Formatter::Formatter(const string &f):
 	advance();
 }
 
-/**
-Returns the result of the formatting operation.  Will throw if not enough
-values have been fed to the formatter.
-*/
 const string &Formatter::str() const
 {
 	if(pos!=fmt.end())
@@ -23,11 +19,6 @@ const string &Formatter::str() const
 	return result;
 }
 
-/**
-Advances the pos iterator to the next conversion, adding literal characters to
-the result.  The iterator is left at the second character of the conversion
-(i.e. after the %).
-*/
 void Formatter::advance()
 {
 	for(; pos!=fmt.end(); ++pos)
@@ -45,10 +36,6 @@ void Formatter::advance()
 	}
 }
 
-/**
-Reads the next conversion from the format string and returns a corresponding
-Fmt object.
-*/
 Fmt Formatter::get_conversion()
 {
 	if(pos==fmt.end())
diff --git a/source/strings/format.h b/source/strings/format.h
index 9264b10..6d8f739 100644
--- a/source/strings/format.h
+++ b/source/strings/format.h
@@ -29,9 +29,18 @@ public:
 		return *this;
 	}
 
+	/** Returns the result of the formatting operation.  Will throw if not
+	enough values have been fed to the formatter. */
 	const std::string &str() const;
+
 private:
+	/** Advances the iterator to the next conversion, adding literal characters
+	to the result.  The iterator is left at the second character of the
+	conversion (i.e. after the %). */
 	void advance();
+
+	/** Reads the next conversion from the format string and returns a
+	corresponding Fmt object. */
 	Fmt get_conversion();
 };
 
diff --git a/source/strings/regex.cpp b/source/strings/regex.cpp
index 5b04764..60b8ed1 100644
--- a/source/strings/regex.cpp
+++ b/source/strings/regex.cpp
@@ -13,16 +13,16 @@ template<typename T>
 void write_int(T n, Msp::Regex::Code &code)
 {
 	for(unsigned i=0; i<sizeof(T); ++i)
-		code += (n>>i*8)&0xFF;
+		code += (n>>(i*8))&0xFF;
 }
 
-/** Reads an integer from a Regex code stream, in little-endian order. */
+/** Reads an integer from a Regex code string, in little-endian order. */
 template<typename T>
 T read_int(Msp::Regex::Code::const_iterator &c)
 {
 	T result = 0;
 	for(unsigned i=0; i<sizeof(T); ++i)
-		result += (*c++)<<i*8;
+		result += (*c++)<<(i*8);
 	return result;
 }
 
diff --git a/source/time/datetime.cpp b/source/time/datetime.cpp
index 8feeff2..bf82411 100644
--- a/source/time/datetime.cpp
+++ b/source/time/datetime.cpp
@@ -121,7 +121,7 @@ void DateTime::add_days(int days)
 	}
 
 	// Fudge factor for leap day
-	int fudge = (month<=2)?1:0;
+	int fudge = (month<=2) ? 1 : 0;
 
 	// (Almost) every 4 year cycle has 1 leap year and 3 normal years
 	unsigned cycles = days/1461;
@@ -148,7 +148,7 @@ void DateTime::add_days(int days)
 		// We passed a leap year - decrement days
 		if(days==0)
 		{
-			days = is_leap_year(new_year-fudge)?365:364;
+			days = is_leap_year(new_year-fudge) ? 365 : 364;
 			--new_year;
 		}
 		else
@@ -306,10 +306,10 @@ void DateTime::add_raw(RawTime raw)
 		raw += 86400000000LL;
 	}
 
-	usec+=raw%1000000; raw /= 1000000;
-	second+=raw%60;    raw /= 60;
-	minute+=raw%60;    raw /= 60;
-	hour+=raw%24;      raw /= 24;
+	usec += raw%1000000; raw /= 1000000;
+	second += raw%60;    raw /= 60;
+	minute += raw%60;    raw /= 60;
+	hour += raw%24;      raw /= 24;
 
 	add_days(days);
 	normalize();
diff --git a/source/time/datetime.h b/source/time/datetime.h
index f00d377..f065d32 100644
--- a/source/time/datetime.h
+++ b/source/time/datetime.h
@@ -23,14 +23,14 @@ TimeStamp is a better choice.
 class DateTime
 {
 private:
-	int           year;
+	int year;
 	unsigned char month;
 	unsigned char mday;
 	unsigned char hour;
 	unsigned char minute;
 	unsigned char second;
-	unsigned      usec;
-	TimeZone      zone;
+	unsigned usec;
+	TimeZone zone;
 
 public:
 	DateTime(const TimeStamp &);
@@ -43,13 +43,13 @@ private:
 	void init(int, unsigned char, unsigned char, unsigned char, unsigned char, unsigned char, unsigned);
 
 public:
-	int           get_year() const   { return year; }
-	unsigned char get_month() const  { return month; }
-	unsigned char get_mday() const   { return mday; }
-	unsigned char get_hour() const   { return hour; }
+	int get_year() const { return year; }
+	unsigned char get_month() const { return month; }
+	unsigned char get_mday() const { return mday; }
+	unsigned char get_hour() const { return hour; }
 	unsigned char get_minute() const { return minute; }
 	unsigned char get_second() const { return second; }
-	unsigned      get_usec() const   { return usec; }
+	unsigned get_usec() const { return usec; }
 
 	void add_days(int);
 	void set_timezone(const TimeZone &);
diff --git a/source/time/timedelta.h b/source/time/timedelta.h
index c290f26..972ee26 100644
--- a/source/time/timedelta.h
+++ b/source/time/timedelta.h
@@ -1,7 +1,7 @@
 #ifndef MSP_TIME_TIMEDELTA_H_
 #define MSP_TIME_TIMEDELTA_H_
 
-#include <time.h>
+#include <ctime>
 #include <msp/strings/lexicalcast.h>
 #include "rawtime.h"
 
@@ -17,58 +17,52 @@ private:
 	RawTime usec;
 
 public:
-	/**
-	Constructs a zero TimeDelta.
-	*/
+	/** Constructs a zero TimeDelta. */
 	TimeDelta(): usec(0) { }
 
-	/**
-	Constructs a TimeDelta from a plain number.  The purpose of this is to allow
-	serialization together with the raw() function.  For creating TimeDeltas
-	with a specific length, see units.h.
-	*/
+	/** Constructs a TimeDelta from a plain number.  The purpose of this is to
+	allow serialization together with the raw() function.  For creating
+	TimeDeltas with a specific length, see units.h. */
 	explicit TimeDelta(RawTime u): usec(u) { }
 
-	/**
-	Returns the raw number stored inside the TimeDelta.  This should only be used
-	for serialization and the result should not be interpreted in any way.
-	*/
+	/** Returns the raw number stored inside the TimeDelta.  This should only be used
+	for serialization and the result should not be interpreted in any way. */
 	RawTime raw() const { return usec; }
 
-	TimeDelta operator+(const TimeDelta &t) const  { return TimeDelta(usec+t.usec); }
-	TimeDelta &operator+=(const TimeDelta &t)      { usec+=t.usec; return *this; }
-	TimeDelta operator-(const TimeDelta &t) const  { return TimeDelta(usec-t.usec); }
-	TimeDelta &operator-=(const TimeDelta &t)      { usec-=t.usec; return *this; }
+	TimeDelta operator+(const TimeDelta &t) const { return TimeDelta(usec+t.usec); }
+	TimeDelta &operator+=(const TimeDelta &t) { usec += t.usec; return *this; }
+	TimeDelta operator-(const TimeDelta &t) const { return TimeDelta(usec-t.usec); }
+	TimeDelta &operator-=(const TimeDelta &t) { usec -= t.usec; return *this; }
 
 	template<typename T>
-	TimeDelta operator*(T a) const                 { return TimeDelta(RawTime(usec*a)); }
+	TimeDelta operator*(T a) const { return TimeDelta(RawTime(usec*a)); }
 	template<typename T>
-	TimeDelta &operator*=(T a)                     { usec=RawTime(usec*a); return *this; }
+	TimeDelta &operator*=(T a) { usec = RawTime(usec*a); return *this; }
 
 	template<typename T>
-	TimeDelta operator/(T a) const                 { return TimeDelta(RawTime(usec/a)); }
+	TimeDelta operator/(T a) const { return TimeDelta(RawTime(usec/a)); }
 	template<typename T>
-	TimeDelta &operator/=(T a)                     { usec=RawTime(usec/a); return *this; }
+	TimeDelta &operator/=(T a) { usec = RawTime(usec/a); return *this; }
 
-	double    operator/(const TimeDelta &t) const  { return double(usec)/t.usec; }
+	double operator/(const TimeDelta &t) const { return double(usec)/t.usec; }
 
-	bool      operator>(const TimeDelta &t) const  { return usec>t.usec; }
-	bool      operator>=(const TimeDelta &t) const { return usec>=t.usec; }
-	bool      operator<(const TimeDelta &t) const  { return usec<t.usec; }
-	bool      operator<=(const TimeDelta &t) const { return usec<=t.usec; }
-	bool      operator==(const TimeDelta &t) const { return usec==t.usec; }
-	bool      operator!=(const TimeDelta &t) const { return usec!=t.usec; }
+	bool operator>(const TimeDelta &t) const { return usec>t.usec; }
+	bool operator>=(const TimeDelta &t) const { return usec>=t.usec; }
+	bool operator<(const TimeDelta &t) const { return usec<t.usec; }
+	bool operator<=(const TimeDelta &t) const { return usec<=t.usec; }
+	bool operator==(const TimeDelta &t) const { return usec==t.usec; }
+	bool operator!=(const TimeDelta &t) const { return usec!=t.usec; }
 
 #ifndef WIN32
 	operator timeval() const { return rawtime_to_timeval(usec); }
 	operator timespec() const { return rawtime_to_timespec(usec); }
 #endif
 
-	operator const void *() const                  { return usec ? this : 0; }
+	operator const void *() const { return usec ? this : 0; }
 };
 
 template<typename T>
-inline TimeDelta operator*(T a, const TimeDelta &t)   { return t*a; }
+inline TimeDelta operator*(T a, const TimeDelta &t) { return t*a; }
 
 void operator<<(LexicalConverter &, const TimeDelta &);
 
diff --git a/source/time/timer.h b/source/time/timer.h
index b080f82..7566c3d 100644
--- a/source/time/timer.h
+++ b/source/time/timer.h
@@ -53,30 +53,22 @@ private:
 public:
 	~Timer();
 
-	/**
-	Adds a timer that will be executed periodically as long as the timeout
-	signal hander returns true.
-	*/
+	/** Adds a timer that will be executed periodically as long as the timeout
+	signal hander returns true. */
 	Slot &add(const TimeDelta &);
 
-	/**
-	Adds a timer that will be executed once at a specific time.  The return
-	value of the timeout signal handler is ignored.
-	*/
+	/** Adds a timer that will be executed once at a specific time.  The return
+	value of the timeout signal handler is ignored. */
 	Slot &add(const TimeStamp &);
 
-	/**
-	Cancels a previously added timer.
-	*/
+	/** Cancels a previously added timer. */
 	void cancel(Slot &);
 
-	/**
-	Checks all timers, executing any that have timed out.  If block is true,
+	/** Checks all timers, executing any that have timed out.  If block is true,
 	waits until one times out.
 
 	Note: If there are no active timers when a blocking tick is executed, it
-	won't return until a timer is added from another thread.
-	*/
+	won't return until a timer is added from another thread. */
 	void tick(bool block = true);
 
 	TimeStamp get_next_timeout() const;
diff --git a/source/time/timestamp.h b/source/time/timestamp.h
index cb38279..41fc1e5 100644
--- a/source/time/timestamp.h
+++ b/source/time/timestamp.h
@@ -19,40 +19,34 @@ private:
 	RawTime usec;
 
 public:
-	/**
-	Construct a TimeStamp that represents an arbitarily distant point in the
-	past.  It's guaranteed to be less than any valid timestamp.
-	*/
+	/** Construct a TimeStamp that represents an arbitarily distant point in the
+	past.  It's guaranteed to be less than any valid timestamp. */
 	TimeStamp(): usec(0) { }
 
-	/**
-	Constructs a TimeStamp from a plain number.  The purpose of this is to allow
-	serialization together with the raw() function.
-	*/
+	/** Constructs a TimeStamp from a plain number.  The purpose of this is to allow
+	serialization together with the raw() function. */
 	explicit TimeStamp(RawTime u): usec(u) { }
 
-	/**
-	Returns the raw number stored inside the TimeStamp.  This value should be
-	considered opaque and only be used for serialization.
-	*/
+	/** Returns the raw number stored inside the TimeStamp.  This value should be
+	considered opaque and only be used for serialization. */
 	RawTime raw() const { return usec; }
 
 	time_t to_unixtime() const { return usec/1000000LL; }
 
-	TimeStamp operator+(const TimeDelta &t) const  { return TimeStamp(usec+t.raw()); }
-	TimeStamp &operator+=(const TimeDelta &t)      { usec+=t.raw(); return *this; }
-	TimeStamp operator-(const TimeDelta &t) const  { return TimeStamp(usec-t.raw()); }
-	TimeStamp &operator-=(const TimeDelta &t)      { usec-=t.raw(); return *this; }
-	TimeDelta operator-(const TimeStamp &t) const  { return TimeDelta(usec-t.usec); }
+	TimeStamp operator+(const TimeDelta &t) const { return TimeStamp(usec+t.raw()); }
+	TimeStamp &operator+=(const TimeDelta &t) { usec += t.raw(); return *this; }
+	TimeStamp operator-(const TimeDelta &t) const { return TimeStamp(usec-t.raw()); }
+	TimeStamp &operator-=(const TimeDelta &t) { usec -= t.raw(); return *this; }
+	TimeDelta operator-(const TimeStamp &t) const { return TimeDelta(usec-t.usec); }
 
-	bool      operator>=(const TimeStamp &t) const { return usec>=t.usec; }
-	bool      operator>(const TimeStamp &t) const  { return usec>t.usec; }
-	bool      operator<=(const TimeStamp &t) const { return usec<=t.usec; }
-	bool      operator<(const TimeStamp &t) const  { return usec<t.usec; }
-	bool      operator==(const TimeStamp &t) const { return usec==t.usec; }
-	bool      operator!=(const TimeStamp &t) const { return usec!=t.usec; }
+	bool operator>=(const TimeStamp &t) const { return usec>=t.usec; }
+	bool operator>(const TimeStamp &t) const { return usec>t.usec; }
+	bool operator<=(const TimeStamp &t) const { return usec<=t.usec; }
+	bool operator<(const TimeStamp &t) const { return usec<t.usec; }
+	bool operator==(const TimeStamp &t) const { return usec==t.usec; }
+	bool operator!=(const TimeStamp &t) const { return usec!=t.usec; }
 
-	operator const void *() const                  { return usec>0 ? this : 0; }
+	operator const void *() const { return usec>0 ? this : 0; }
 
 #ifndef WIN32
 	operator timeval() const { return rawtime_to_timeval(usec); }
diff --git a/source/time/timezone.cpp b/source/time/timezone.cpp
index 56fcf8f..873829d 100644
--- a/source/time/timezone.cpp
+++ b/source/time/timezone.cpp
@@ -4,8 +4,8 @@
 #else
 #include <fcntl.h>
 #endif
-#include <msp/core/systemerror.h>
 #include <msp/strings/format.h>
+#include <msp/core/systemerror.h>
 #include "timestamp.h"
 #include "timezone.h"
 #include "units.h"
diff --git a/source/time/utils.cpp b/source/time/utils.cpp
index 7da0aed..d69febc 100644
--- a/source/time/utils.cpp
+++ b/source/time/utils.cpp
@@ -17,9 +17,6 @@ using namespace std;
 namespace Msp {
 namespace Time {
 
-/**
-Returns the current timestamp.
-*/
 TimeStamp now()
 {
 #ifndef WIN32
@@ -55,9 +52,6 @@ string format_now(const string &fmt)
 	return DateTime(now()).format(fmt);
 }
 
-/**
-Returns the CPU time used by the program so far.
-*/
 TimeDelta get_cpu_time()
 {
 #ifndef WIN32
@@ -70,9 +64,6 @@ TimeDelta get_cpu_time()
 #endif
 }
 
-/**
-Sleeps for the given time.
-*/
 void sleep(const TimeDelta &d)
 {
 #ifndef WIN32
diff --git a/source/time/utils.h b/source/time/utils.h
index 0a2b351..00b6ef8 100644
--- a/source/time/utils.h
+++ b/source/time/utils.h
@@ -9,10 +9,16 @@ namespace Time {
 class TimeDelta;
 class TimeStamp;
 
-extern TimeStamp now();
-extern std::string format_now(const std::string &);
-extern TimeDelta get_cpu_time();
-extern void sleep(const TimeDelta &);
+/** Returns the current timestamp. */
+TimeStamp now();
+
+std::string format_now(const std::string &);
+
+/** Returns the CPU time used by the program so far. */
+TimeDelta get_cpu_time();
+
+/** Sleeps for the given duration. */
+void sleep(const TimeDelta &);
 
 } // namespace Time
 } // namespace Msp