From 7a461855eb52db188902f96512f550a102b4bccf Mon Sep 17 00:00:00 2001 From: crs Date: Fri, 26 Jul 2002 18:28:18 +0000 Subject: [PATCH] added doxygen comments for all relevant headers in base. --- base/CFunctionJob.h | 5 ++ base/CLog.h | 163 +++++++++++++++++++++++++++++++++++--------- base/CStopwatch.h | 79 +++++++++++++++------ base/CString.h | 86 ++++++++++++++++------- base/CUnicode.h | 89 +++++++++++++++++++++--- base/IInterface.h | 6 ++ base/IJob.h | 5 ++ base/TMethodJob.h | 5 ++ base/XBase.h | 34 +++++++-- base/common.h | 2 + 10 files changed, 380 insertions(+), 94 deletions(-) diff --git a/base/CFunctionJob.h b/base/CFunctionJob.h index b1c786e0..311ceaf9 100644 --- a/base/CFunctionJob.h +++ b/base/CFunctionJob.h @@ -3,8 +3,13 @@ #include "IJob.h" +//! Use a function as a job +/*! +A job class that invokes a function. +*/ class CFunctionJob : public IJob { public: + //! run() invokes \c func(arg) CFunctionJob(void (*func)(void*), void* arg = NULL); virtual ~CFunctionJob(); diff --git a/base/CLog.h b/base/CLog.h index 834b5bec..085016e2 100644 --- a/base/CLog.h +++ b/base/CLog.h @@ -4,54 +4,114 @@ #include "common.h" #include +//! Logging facility +/*! +The logging class; all console output should go through this class. +It supports multithread safe operation, several message priority levels, +filtering by priority, and output redirection. The macros log() and +clog() provide convenient access. +*/ class CLog { public: - enum { - kFATAL, - kERROR, - kWARNING, - kNOTE, - kINFO, - kDEBUG, - kDEBUG1, - kDEBUG2 + //! Log levels + /*! + The logging priority levels in order of highest to lowest priority. + */ + enum ELevel { + kFATAL, //!< For fatal errors + kERROR, //!< For serious errors + kWARNING, //!< For minor errors and warnings + kNOTE, //!< For messages about notable events + kINFO, //!< For informational messages + kDEBUG, //!< For important debugging messages + kDEBUG1, //!< For more detailed debugging messages + kDEBUG2 //!< For even more detailed debugging messages }; - // type of outputter function. return false if CLog should use - // the default outputter, true otherwise. - typedef bool (*Outputter)(int priority, const char*); + //! Outputter function. + /*! + Type of outputter function. The outputter should write \c message, + which has the given \c priority, to a log and return true. Or it can + return false to let CLog use the default outputter. + */ + typedef bool (*Outputter)(int priority, const char* message); - // type of lock/unlock function + //! Locking function + /*! + Type of lock/unlock function. If \c lock is true then block other + threads that try to lock until this thread unlocks. If \c lock is + false then unlock and allow another (waiting) thread to lock. + */ typedef void (*Lock)(bool lock); - // print a log message - static void print(const char*, ...); - static void printt(const char* file, int line, const char*, ...); + //! @name manipulators + //@{ - // get/set the function used to write the log. a NULL outputter - // means to use the default which is fprintf(stderr, ...). note - // that the outputter should not call CLog methods but, if it - // does, the current lock function must permit recursive locks. + //! Set the function used to write the log + /*! + Sets the function used to write to the log. The outputter function + is called with the formatted string to write and the priority level. + CLog will have already filtered messages below the current filter + priority. A NULL outputter means to use the default which is to print + to stderr. Note that the outputter should not call CLog methods but, + if it does, the current lock function must permit recursive locks. + */ static void setOutputter(Outputter); - static Outputter getOutputter(); - // get/set the lock/unlock function. use setLock(NULL) to remove - // the locking function. note that the lock function is used when - // retrieving the lock function. there is no default lock function. + //! Set the lock/unlock function + /*! + Set the lock/unlock function. Use setLock(NULL) to remove the + locking function. There is no default lock function; do not call + CLog from multiple threads unless a working lock function has been + installed. + */ static void setLock(Lock); - static Lock getLock(); - // get/set the minimum priority filter. any message below this - // priority is discarded. the default priority is 4 (INFO) - // (unless built without NDEBUG in which case it's 5 (DEBUG)). - // the default can be overridden by setting the SYN_LOG_PRI env - // var to "FATAL", "ERROR", etc. setFilter(const char*) returns - // true if the priority name was recognized; if name == NULL - // then it simply returns true. + //! Set the minimum priority filter. + /*! + Set the filter. Messages below this priority are discarded. + The default priority is 4 (INFO) (unless built without NDEBUG + in which case it's 5 (DEBUG)). The default can be overridden + by setting the SYN_LOG_PRI env var to "FATAL", "ERROR", etc. + setFilter(const char*) returns true if the priority \c name was + recognized; if \c name is NULL then it simply returns true. + */ static bool setFilter(const char* name); static void setFilter(int); + + //@} + //! @name accessors + //@{ + + //! Print a log message + /*! + Print a log message using the printf-like \c format and arguments. + */ + static void print(const char* format, ...); + + //! Print a log message + /*! + Print a log message using the printf-like \c format and arguments + preceded by the filename and line number. + */ + static void printt(const char* file, int line, + const char* format, ...); + + //! Get the function used to write the log + static Outputter getOutputter(); + + //! Get the lock/unlock function + /*! + Get the lock/unlock function. Note that the lock function is + used when retrieving the lock function. + */ + static Lock getLock(); + + //! Get the minimum priority level. static int getFilter(); + //@} + private: class CHoldLock { public: @@ -75,6 +135,45 @@ private: static int s_maxPriority; }; +/*! +\def log(arg) +Write to the log. Because macros cannot accept variable arguments, this +should be invoked like so: +\code +log((CLOG_XXX "%d and %d are %s", x, y, x == y ? "equal" : "not equal")); +\endcode +In particular, notice the double open and close parentheses. Also note +that there is no comma after the \c CLOG_XXX. The \c XXX should be +replaced by one of enumerants in \c CLog::ELevel without the leading +\c k. For example, \c CLOG_INFO. The special \c CLOG_PRINT level will +not be filtered and is never prefixed by the filename and line number. + +If \c NOLOGGING is defined during the build then this macro expands to +nothing. If \c NDEBUG is defined during the build then it expands to a +call to CLog::print. Otherwise it expands to a call to CLog::printt, +which includes the filename and line number. +*/ + +/*! +\def logc(expr, arg) +Write to the log if and only if expr is true. Because macros cannot accept +variable arguments, this should be invoked like so: +\code +clog(x == y, (CLOG_XXX "%d and %d are equal", x, y)); +\endcode +In particular, notice the parentheses around everything after the boolean +expression. Also note that there is no comma after the \c CLOG_XXX. +The \c XXX should be replaced by one of enumerants in \c CLog::ELevel +without the leading \c k. For example, \c CLOG_INFO. The special +\c CLOG_PRINT level will not be filtered and is never prefixed by the +filename and line number. + +If \c NOLOGGING is defined during the build then this macro expands to +nothing. If \c NDEBUG is defined during the build then it expands to a +call to CLog::print. Otherwise it expands to a call to CLog::printt, +which includes the filename and line number. +*/ + #if defined(NOLOGGING) #define log(_a1) #define logc(_a1, _a2) diff --git a/base/CStopwatch.h b/base/CStopwatch.h index 791729f2..8817a67a 100644 --- a/base/CStopwatch.h +++ b/base/CStopwatch.h @@ -3,47 +3,84 @@ #include "common.h" +//! A timer class +/*! +This class measures time intervals. All time interval measurement +should use this class. +*/ class CStopwatch { public: - // the default constructor does an implicit reset() or setTrigger(). - // if triggered == false then the clock starts ticking. + /*! + The default constructor does an implicit reset() or setTrigger(). + If triggered == false then the clock starts ticking. + */ CStopwatch(bool triggered = false); ~CStopwatch(); - // manipulators + //! @name manipulators + //@{ - // set the start time to the current time, returning the time since - // the last reset. this does not remove the trigger if it's set nor - // does it start a stopped clock. if the clock is stopped then - // subsequent reset()'s will return 0. + //! Reset the timer to zero + /*! + Set the start time to the current time, returning the time since + the last reset. This does not remove the trigger if it's set nor + does it start a stopped clock. If the clock is stopped then + subsequent reset()'s will return 0. + */ double reset(); - // stop and start the stopwatch. while stopped, no time elapses. - // stop() does not remove the trigger but start() does, even if - // the clock was already started. + //! Stop the timer + /*! + Stop the stopwatch. The time interval while stopped is not + counted by the stopwatch. stop() does not remove the trigger. + Has no effect if already stopped. + */ void stop(); + + //! Start the timer + /*! + Start the stopwatch. start() removes the trigger, even if the + stopwatch was already started. + */ void start(); - // setTrigger() stops the clock like stop() except there's an - // implicit start() the next time (non-const) getTime() is called. - // this is useful when you want the clock to start the first time - // you check it. + //! Stop the timer and set the trigger + /*! + setTrigger() stops the clock like stop() except there's an + implicit start() the next time (non-const) getTime() is called. + This is useful when you want the clock to start the first time + you check it. + */ void setTrigger(); - // return the time since the last reset() (or call reset() and - // return zero if the trigger is set). + //! Get elapsed time + /*! + Returns the time since the last reset() (or calls reset() and + returns zero if the trigger is set). + */ double getTime(); + //! Same as getTime() operator double(); + //@} + //! @name accessors + //@{ - // accessors - - // returns true if the watch is stopped + //! Check if timer is stopped + /*! + Returns true if the stopwatch is stopped. + */ bool isStopped() const; - // return the time since the last reset(). these cannot trigger - // the clock to start so if the trigger is set it's as if it wasn't. + // return the time since the last reset(). + //! Get elapsed time + /*! + Returns the time since the last reset(). This cannot trigger the + stopwatch to start and will not clear the trigger. + */ double getTime() const; + //! Same as getTime() const operator double() const; + //@} private: double getClock() const; diff --git a/base/CString.h b/base/CString.h index 56c3a690..0f74cba5 100644 --- a/base/CString.h +++ b/base/CString.h @@ -6,45 +6,83 @@ #include #include "stdpost.h" +// use standard C++ string class for our string class typedef std::string CString; +//! String utilities +/*! +This class provides various functions for string manipulation. +*/ class CStringUtil { public: - // format a string using positional arguments. fmt has literal - // characters and conversion specifications introduced by `%': - // %% literal `%' - // %{n} positional element n, n a positive integer, {} are literal - // all arguments in the variable list are const char*. positional - // elements are indexed from 1. + //! Format positional arguments + /*! + Format a string using positional arguments. fmt has literal + characters and conversion specifications introduced by `\%': + - \c\%\% -- literal `\%' + - \c\%{n} -- positional element n, n a positive integer, {} are literal + + All arguments in the variable list are const char*. Positional + elements are indexed from 1. + */ static CString format(const char* fmt, ...); + + //! Format positional arguments + /*! + Same as format() except takes va_list. + */ static CString vformat(const char* fmt, va_list); - // print a string using printf-style formatting + //! Print a string using printf-style formatting + /*! + Equivalent to printf() except the result is returned as a CString. + */ static CString print(const char* fmt, ...); + + //! Print a string using printf-style formatting + /*! + Same as print() except takes va_list. + */ static CString vprint(const char* fmt, va_list); - // like print but print into a given buffer. if the resulting string - // will not fit into the buffer then a new buffer is allocated and - // returned, otherwise the input buffer is returned. the caller must - // delete[] the returned buffer if is not the passed-in buffer. - // - // prefix and suffix must be >= 0. exactly prefix characters and - // at least suffix characters are available in the buffer before - // and after the printed string, respectively. bufferLength is the - // length of buffer and should not be adjusted by the caller to - // account for prefix or suffix. + //! Print a string using printf-style formatting into a buffer + /*! + This is like print but print into a given buffer. If the resulting + string will not fit into \c buffer then a new buffer is allocated and + returned, otherwise \c buffer is returned. the caller must delete[] + the returned memory if is not \c buffer. + + \c prefix and \c suffix must be >= 0. Exactly \c prefix characters and + at least \c suffix characters are available in the buffer before + and after the printed string, respectively. \c bufferLength is the + length of buffer and should not be adjusted by the caller to + account for \c prefix or \c suffix. + */ static char* vsprint(char* buffer, int bufferLength, int prefix, int suffix, const char* fmt, va_list); + //! Case-insensitive comparisons + /*! + This class provides case-insensitve comparison functions. + */ class CaselessCmp { public: - bool operator()(const CString&, const CString&) const; - static bool less(const CString&, const CString&); - static bool equal(const CString&, const CString&); - static bool cmpLess(const CString::value_type&, - const CString::value_type&); - static bool cmpEqual(const CString::value_type&, - const CString::value_type&); + //! Same as less() + bool operator()(const CString& a, const CString& b) const; + + //! Returns true iff \c a is lexicographically less than \c b + static bool less(const CString& a, const CString& b); + + //! Returns true iff \c a is lexicographically equal to \c b + static bool equal(const CString& a, const CString& b); + + //! Returns true iff \c a is lexicographically less than \c b + static bool cmpLess(const CString::value_type& a, + const CString::value_type& b); + + //! Returns true iff \c a is lexicographically equal to \c b + static bool cmpEqual(const CString::value_type& a, + const CString::value_type& b); }; }; diff --git a/base/CUnicode.h b/base/CUnicode.h index dc2f4df2..aa6d07c3 100644 --- a/base/CUnicode.h +++ b/base/CUnicode.h @@ -5,33 +5,100 @@ #include "BasicTypes.h" #include +//! Unicode utility functions +/*! +This class provides functions for converting between various Unicode +encodings and the current locale encoding. +*/ class CUnicode { public: - // returns true iff the string contains a valid sequence of UTF-8 - // encoded characters. + //! @name accessors + //@{ + + //! Test UTF-8 string for validity + /*! + Returns true iff the string contains a valid sequence of UTF-8 + encoded characters. + */ static bool isUTF8(const CString&); - // convert from UTF-8 encoding to other encodings. if errors is - // not NULL then it gets true if any characters could not be - // encoded in the target encoding and false otherwise. note - // that decoding errors do not set errors to error. UTF8ToText() - // converts to the current locale's (multibyte) encoding. + //! Convert from UTF-8 to UCS-2 encoding + /*! + Convert from UTF-8 to UCS-2. If errors is not NULL then *errors + is set to true iff any character could not be encoded in UCS-2. + Decoding errors do not set *errors. + */ static CString UTF8ToUCS2(const CString&, bool* errors = NULL); + + //! Convert from UTF-8 to UCS-4 encoding + /*! + Convert from UTF-8 to UCS-4. If errors is not NULL then *errors + is set to true iff any character could not be encoded in UCS-4. + Decoding errors do not set *errors. + */ static CString UTF8ToUCS4(const CString&, bool* errors = NULL); + + //! Convert from UTF-8 to UTF-16 encoding + /*! + Convert from UTF-8 to UTF-16. If errors is not NULL then *errors + is set to true iff any character could not be encoded in UTF-16. + Decoding errors do not set *errors. + */ static CString UTF8ToUTF16(const CString&, bool* errors = NULL); + + //! Convert from UTF-8 to UTF-32 encoding + /*! + Convert from UTF-8 to UTF-32. If errors is not NULL then *errors + is set to true iff any character could not be encoded in UTF-32. + Decoding errors do not set *errors. + */ static CString UTF8ToUTF32(const CString&, bool* errors = NULL); + + //! Convert from UTF-8 to the current locale encoding + /*! + Convert from UTF-8 to the current locale encoding. If errors is not + NULL then *errors is set to true iff any character could not be encoded. + Decoding errors do not set *errors. + */ static CString UTF8ToText(const CString&, bool* errors = NULL); - // convert from some encoding to UTF-8. if errors is not NULL - // then it gets true if any characters could not be decoded and - // false otherwise. textToUTF8() converts from the current - // locale's (multibyte) encoding. + //! Convert from UCS-2 to UTF-8 + /*! + Convert from UCS-2 to UTF-8. If errors is not NULL then *errors is + set to true iff any character could not be decoded. + */ static CString UCS2ToUTF8(const CString&, bool* errors = NULL); + + //! Convert from UCS-4 to UTF-8 + /*! + Convert from UCS-4 to UTF-8. If errors is not NULL then *errors is + set to true iff any character could not be decoded. + */ static CString UCS4ToUTF8(const CString&, bool* errors = NULL); + + //! Convert from UTF-16 to UTF-8 + /*! + Convert from UTF-16 to UTF-8. If errors is not NULL then *errors is + set to true iff any character could not be decoded. + */ static CString UTF16ToUTF8(const CString&, bool* errors = NULL); + + //! Convert from UTF-32 to UTF-8 + /*! + Convert from UTF-32 to UTF-8. If errors is not NULL then *errors is + set to true iff any character could not be decoded. + */ static CString UTF32ToUTF8(const CString&, bool* errors = NULL); + + //! Convert from the current locale encoding to UTF-8 + /*! + Convert from the current locale encoding to UTF-8. If errors is not + NULL then *errors is set to true iff any character could not be decoded. + */ static CString textToUTF8(const CString&, bool* errors = NULL); + //@} + private: // convert UTF8 to wchar_t string (using whatever encoding is native // to the platform). caller must delete[] the returned string. the diff --git a/base/IInterface.h b/base/IInterface.h index 52b4bde4..4f85e1be 100644 --- a/base/IInterface.h +++ b/base/IInterface.h @@ -3,8 +3,14 @@ #include "common.h" +//! Base class of interfaces +/*! +This is the base class of all interface classes. An interface class has +only pure virtual methods. +*/ class IInterface { public: + //! Interface destructor does nothing virtual ~IInterface() { } }; diff --git a/base/IJob.h b/base/IJob.h index f13a359c..b83c0d80 100644 --- a/base/IJob.h +++ b/base/IJob.h @@ -3,8 +3,13 @@ #include "IInterface.h" +//! Job interface +/*! +A job is an interface for executing some function. +*/ class IJob : public IInterface { public: + //! Run the job virtual void run() = 0; }; diff --git a/base/TMethodJob.h b/base/TMethodJob.h index 950b95c8..ef63e22e 100644 --- a/base/TMethodJob.h +++ b/base/TMethodJob.h @@ -3,9 +3,14 @@ #include "IJob.h" +//! Use a function as a job +/*! +A job class that invokes a member function. +*/ template class TMethodJob : public IJob { public: + //! run() invokes \c object->method(arg) TMethodJob(T* object, void (T::*method)(void*), void* arg = NULL); virtual ~TMethodJob(); diff --git a/base/XBase.h b/base/XBase.h index 1e4c208c..a35a33be 100644 --- a/base/XBase.h +++ b/base/XBase.h @@ -6,9 +6,15 @@ #include #include "stdpost.h" +//! Exception base class +/*! +This is the base class of most exception types. +*/ class XBase : public std::exception { public: + //! Use getWhat() as the result of what() XBase(); + //! Use \c msg as the result of what() XBase(const CString& msg); virtual ~XBase(); @@ -16,10 +22,15 @@ public: virtual const char* what() const; protected: - // returns a human readable string describing the exception + //! Get a human readable string describing the exception virtual CString getWhat() const throw() = 0; - // look up a message and format it + //! Format a string + /*! + Looks up a message format using \c id, using \c defaultFormat if + no format can be found, then replaces positional parameters in + the format string and returns the result. + */ virtual CString format(const char* id, const char* defaultFormat, ...) const throw(); @@ -27,18 +38,29 @@ private: mutable CString m_what; }; +//! Mix-in for handling \c errno +/*! +This mix-in class for exception classes provides storage and query of +\c errno. +*/ class MXErrno { public: + //! Save \c errno as the error code MXErrno(); - MXErrno(int); + //! Save \c err as the error code + MXErrno(int err); - // manipulators - - // accessors + //! @name accessors + //@{ + //! Get the error code int getErrno() const; + + //! Get the human readable string for the error code const char* getErrstr() const; + //@} + private: int m_errno; }; diff --git a/base/common.h b/base/common.h index 00b9fd87..a03fd9c1 100644 --- a/base/common.h +++ b/base/common.h @@ -1,6 +1,8 @@ #ifndef COMMON_H #define COMMON_H +// this file should be included, directly or indirectly by every other. + #if HAVE_CONFIG_H # include "config.h" #endif