[Orxonox-commit 2662] r7367 - code/branches/doc/src/libraries/util
rgrieder at orxonox.net
rgrieder at orxonox.net
Mon Sep 6 15:51:29 CEST 2010
Author: rgrieder
Date: 2010-09-06 15:51:29 +0200 (Mon, 06 Sep 2010)
New Revision: 7367
Modified:
code/branches/doc/src/libraries/util/Clock.cc
code/branches/doc/src/libraries/util/Clock.h
code/branches/doc/src/libraries/util/Exception.cc
code/branches/doc/src/libraries/util/Exception.h
code/branches/doc/src/libraries/util/ExprParser.h
code/branches/doc/src/libraries/util/MathConvert.h
code/branches/doc/src/libraries/util/OrxAssert.h
code/branches/doc/src/libraries/util/OrxEnum.h
code/branches/doc/src/libraries/util/TriBool.h
Log:
Added Doxygen documentation for ExprParser, MathConvert, OrxEnum, OrxAssert and TriBool.
Adjusted Doxygen documentation for Clock and Exception.
Modified: code/branches/doc/src/libraries/util/Clock.cc
===================================================================
--- code/branches/doc/src/libraries/util/Clock.cc 2010-09-06 12:54:21 UTC (rev 7366)
+++ code/branches/doc/src/libraries/util/Clock.cc 2010-09-06 13:51:29 UTC (rev 7367)
@@ -44,15 +44,6 @@
delete timer_;
}
- /**
- @remarks
- Mind the types! Ogre::Timer::getMicroseconds() will return an unsigned
- long, which will eventually overflow. But if you use the subtraction of
- the current time minus the last time the timer gave us and sum these up to
- a 64 bit integer, we get the desired result. <br>
- Also mind that we don't have to store the last timer's time as unsigned long
- as well because (unsigned long)tickTime_ will do exactly that.
- */
void Clock::capture()
{
tickDt_ = timer_->getMicroseconds() - (unsigned long)tickTime_;
Modified: code/branches/doc/src/libraries/util/Clock.h
===================================================================
--- code/branches/doc/src/libraries/util/Clock.h 2010-09-06 12:54:21 UTC (rev 7366)
+++ code/branches/doc/src/libraries/util/Clock.h 2010-09-06 13:51:29 UTC (rev 7367)
@@ -40,42 +40,51 @@
incrementally capture the time and then distribute that time information
via Clock& references (for instance for the game tick). <br>
Precision: <br>
+ @par Precision
The maximum precision is given by the Ogre::Timer and that is somewhere
in the microsecond range for both Windows and UNIX.
- @remarks
+ @par Remarks for Usage on Windows
For proper functionality this class MUST be used in the same thread! <br>
- Further more it might be possible that the Ogre::Timer has a performance
- caveat on Windows because it will only capture the time on the same
- CPU core. Confining the main thread to one process could speed up the game.
- See command line argument 'limitToCPU'.
+ Furthermore it might be possible that the Ogre::Timer has a performance
+ caveat because it will only capture the time on the same CPU core.
+ Confining the main thread to one process could speed up the game.
+ See \ref cmdargspage "Ccommandline Argument" 'limitToCPU' (only on Windows)
*/
class _UtilExport Clock
{
public:
- //! Starts the time at 0
+ /// Starts the time at 0
Clock();
~Clock();
- //! Internally captures the time and stays at that particular time
+ /** Internally captures the time and stays at that particular time
+ @remarks
+ Mind the types! Ogre::Timer::getMicroseconds() will return an unsigned
+ long, which will eventually overflow. But if you use the subtraction of
+ the current time minus the last time the timer gave us and sum these up to
+ a 64 bit integer, we get the desired result. <br>
+ Also mind that we don't have to store the last timer's time as unsigned long
+ as well because (unsigned long)tickTime_ will do exactly that.
+ */
void capture();
- //! Returns the last captured absolute time in microseconds
+ /// Returns the last captured absolute time in microseconds
unsigned long long getMicroseconds() const
{ return tickTime_; }
- //! Returns the last captured absolute time in milliseconds
+ /// Returns the last captured absolute time in milliseconds
unsigned long long getMilliseconds() const
{ return tickTime_ / 1000; }
- //! Returns the last captured absolute time in seconds
+ /// Returns the last captured absolute time in seconds
unsigned long getSeconds() const
{ return static_cast<long> (tickTime_ / 1000000); }
- //! Returns the last captured absolute time in seconds as float
+ /// Returns the last captured absolute time in seconds as float
float getSecondsPrecise() const
{ return static_cast<float>(tickTime_ / 1000000.0f); }
- //! Returns the timespan in seconds between the last two calls to capture()
+ /// Returns the timespan in seconds between the last two calls to capture()
float getDeltaTime() const
{ return tickDtFloat_; }
- //! Returns the timespan in microseconds between the last two calls to capture()
+ /// Returns the timespan in microseconds between the last two calls to capture()
long getDeltaTimeMicroseconds() const
{ return tickDt_; }
@@ -87,13 +96,13 @@
unsigned long long getRealMicroseconds() const;
private:
- //! Undefined
+ /// Undefined
Clock(const Clock& instance);
- Ogre::Timer* timer_; //!< Ogre timer object
- unsigned long long tickTime_; //!< Currently captured time
- long tickDt_; //!< Delta time in microseconds (cache value)
- float tickDtFloat_; //!< Delta time in seconds (cache value)
+ Ogre::Timer* timer_; ///< Ogre timer object
+ unsigned long long tickTime_; ///< Currently captured time
+ long tickDt_; ///< Delta time in microseconds (cache value)
+ float tickDtFloat_; ///< Delta time in seconds (cache value)
};
}
Modified: code/branches/doc/src/libraries/util/Exception.cc
===================================================================
--- code/branches/doc/src/libraries/util/Exception.cc 2010-09-06 12:54:21 UTC (rev 7366)
+++ code/branches/doc/src/libraries/util/Exception.cc 2010-09-06 13:51:29 UTC (rev 7367)
@@ -52,12 +52,6 @@
, lineNumber_(0)
{ }
- /**
- @remarks
- The composed full description gets stored to fullDescription_. But for compliance
- with std::exception, this method has to be const. Hence fullDescription_ is declared
- as mutable.
- */
const std::string& Exception::getFullDescription() const
{
if (fullDescription_.empty())
@@ -88,7 +82,6 @@
return fullDescription_;
}
- //! Returns the error description
const char* Exception::what() const throw()
{
return getDescription().c_str();
Modified: code/branches/doc/src/libraries/util/Exception.h
===================================================================
--- code/branches/doc/src/libraries/util/Exception.h 2010-09-06 12:54:21 UTC (rev 7366)
+++ code/branches/doc/src/libraries/util/Exception.h 2010-09-06 13:51:29 UTC (rev 7367)
@@ -30,6 +30,22 @@
@file
@brief
Declaration of facilities to handle exceptions.
+ at details
+ Any exception thrown should inherit from orxonox::Exception. There is a macro
+ \ref CREATE_ORXONOX_EXCEPTION to create a new exception (you can find a list of
+ available exceptions in the docs of this file). <br>
+ Throwing exception is also very simple:
+ @code
+ ThrowException(General, "Something went wrong");
+ @endcode
+ (\c General is a type of exception, see docs of this file) <br>
+ The exception will automatically contain information about file, line number
+ and function name it occurred in. <br><br>
+ There is also some magic you can do for numbers, etc.:
+ @code
+ ThrowException(General, "Error code: " << myInt << ". more info...");
+ @endcode
+ It works with an std::ostringstream, so you can feed it all sorts of values.
*/
#ifndef _Exception_H__
@@ -44,12 +60,11 @@
namespace orxonox
{
- /**
- @brief
- Base class for all exceptions (derived from std::exception).
+ /** Base class for all exceptions (derived from std::exception).
@details
This class provides support for information about the file, the line
- and the function the error occured.
+ and the function the error occurred.
+ @see Exception.h
*/
class _UtilExport Exception : public std::exception
{
@@ -73,9 +88,15 @@
//! Needed for compatibility with std::exception
virtual ~Exception() throw() { }
+ //! Returns the error description
const char* what() const throw();
- //! Returns a full description with type, line, file and function
+ /** Returns a full description with type, line, file and function
+ @remarks
+ The composed full description gets stored to fullDescription_. But for compliance
+ with std::exception, this method has to be const. Hence fullDescription_ is declared
+ as mutable.
+ */
virtual const std::string& getFullDescription() const;
//! Returns the string name of the exception type
virtual std::string getTypeName() const = 0;
@@ -106,7 +127,7 @@
mutable std::string fullDescription_; //!< Full description with line, file and function
};
-//! Creates a new type of exception that inherits from tracker::Exception
+//! Creates a new type of exception that inherits from orxonox::Exception
#define CREATE_ORXONOX_EXCEPTION(ExceptionName) \
class ExceptionName##Exception : public Exception \
{ \
@@ -128,7 +149,6 @@
// Creates all possible exception types.
// If you want to add a new type, simply copy and adjust a new line here.
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
CREATE_ORXONOX_EXCEPTION(General);
CREATE_ORXONOX_EXCEPTION(FileNotFound);
CREATE_ORXONOX_EXCEPTION(Argument);
@@ -141,11 +161,8 @@
CREATE_ORXONOX_EXCEPTION(GameState);
CREATE_ORXONOX_EXCEPTION(NoGraphics);
CREATE_ORXONOX_EXCEPTION(AbortLoading);
-#endif
- /**
- @brief
- Helper function that forwards an exception and displays the message.
+ /** Helper function that forwards an exception and displays the message.
@details
This is necessary because only when using 'throw' the objects storage is managed.
*/
@@ -157,13 +174,12 @@
return exception;
}
-/**
- at brief
- Throws an exception and logs a message beforehand.
+/** Throws an exception and logs a message beforehand.
@param type
Type of the exception as literal (General, Initialisation, etc.)
@param description
Exception description as string
+ at see Exception.h
*/
#define ThrowException(type, description) \
throw orxonox::exceptionThrowerHelper(type##Exception(static_cast<std::ostringstream&>(std::ostringstream().flush() << description).str(), __LINE__, __FILE__, __FUNCTIONNAME__))
Modified: code/branches/doc/src/libraries/util/ExprParser.h
===================================================================
--- code/branches/doc/src/libraries/util/ExprParser.h 2010-09-06 12:54:21 UTC (rev 7366)
+++ code/branches/doc/src/libraries/util/ExprParser.h 2010-09-06 13:51:29 UTC (rev 7367)
@@ -27,8 +27,8 @@
*/
/**
- @file
- @brief Declaration of FloatParser
+ at file
+ at brief Declaration of FloatParser
*/
#ifndef _FloatParser_H__
@@ -41,6 +41,54 @@
namespace orxonox
{
+ /** Parser for expressions like \c "3 * cos(5 + 4) / a" where \a a is a predeclared
+ variable.
+ @par Usage
+ Using it is rather simple:
+ @code
+ std::string str("3 + 4");
+ ExprParser expr;
+ expr.parse(str);
+ if (expr.getSuccess())
+ {
+ if (!expr.getRemains().empty())
+ {
+ COUT(2) << "Warning: Expression could not be parsed to the end! Remains: '" << expr.getRemains() << '\'' << std::endl;
+ }
+ double result = expr.getResult();
+ }
+ else
+ COUT(1) << "Error: Cannot calculate expression: Parse error." << std::endl;
+ @endcode
+ getRemains() returns the expression after what could be parsed. For instance
+ \c "2*3 text" will return \c "text" as remains.
+ @details
+ The implementation of this class is really old and sort of a trial for
+ a first C++ class by Reto. That explains why it looks more like C than
+ C++... Also some of the variable names are in German. <br>
+ Explaining how it works exactly is probably not possible anymore, but it
+ is based on recursively parsing the expression character by character.
+ That much I can remember.
+ @par Functions, operators and variables supported
+ - Variables:
+ - e
+ - pi
+ - Functions:
+ - sin, asin, sinh, asinh
+ - cos, acos, cosh, acosh
+ - tan, atan, tanh, atanh
+ - int, floor, ceil, abs, sign
+ - pow, sqrt, exp, ln, log
+ - mod, div
+ - min, max
+ - radians, degrees
+ - Operators:
+ - +, -, ! (unary)
+ - +, -, *, /, %, ^, |, &, !, <, >, !=, <=, >=, =
+ @note
+ Operators may not be very consistent with C++ rules, but using the class
+ for plus and minus should be perfectly ok.
+ */
class _UtilExport ExprParser
{
public:
Modified: code/branches/doc/src/libraries/util/MathConvert.h
===================================================================
--- code/branches/doc/src/libraries/util/MathConvert.h 2010-09-06 12:54:21 UTC (rev 7366)
+++ code/branches/doc/src/libraries/util/MathConvert.h 2010-09-06 13:51:29 UTC (rev 7367)
@@ -27,9 +27,9 @@
*/
/**
- @file
- @brief
- Math conversion functions. Definitions are in Math.cc
+ at file
+ at brief
+ Conversion functions for Math types like Ogre::Vector3 (definitions are in Math.cc)
*/
#ifndef _MathConvert_H__
@@ -45,7 +45,7 @@
// Math to string //
////////////////////
- // Vector2 to std::string
+ /// Ogre::Vector2 to std::string conversion
template <>
struct ConverterExplicit<orxonox::Vector2, std::string>
{
@@ -61,7 +61,7 @@
}
};
- // Vector3 to std::string
+ /// Ogre::Vector3 to std::string conversion
template <>
struct ConverterExplicit<orxonox::Vector3, std::string>
{
@@ -77,7 +77,7 @@
}
};
- // Vector4 to std::string
+ /// Ogre::Vector4 to std::string conversion
template <>
struct ConverterExplicit<orxonox::Vector4, std::string>
{
@@ -93,7 +93,7 @@
}
};
- // Quaternion to std::string
+ /// Ogre::Quaternion to std::string conversion
template <>
struct ConverterExplicit<orxonox::Quaternion, std::string>
{
@@ -109,7 +109,7 @@
}
};
- // ColourValue to std::string
+ /// Ogre::ColourValue to std::string conversion
template <>
struct ConverterExplicit<orxonox::ColourValue, std::string>
{
@@ -130,19 +130,19 @@
// string to Math //
////////////////////
- // std::string to Vector2
+ /// std::string to Ogre::Vector2 conversion
template <> struct _UtilExport ConverterFallback<std::string, orxonox::Vector2>
{ static bool convert(orxonox::Vector2* output, const std::string& input); };
- // std::string to Vector3
+ /// std::string to Ogre::Vector3 conversion
template <> struct _UtilExport ConverterFallback<std::string, orxonox::Vector3>
{ static bool convert(orxonox::Vector3* output, const std::string& input); };
- // std::string to Vector4
+ /// std::string to Ogre::Vector4 conversion
template <> struct _UtilExport ConverterFallback<std::string, orxonox::Vector4>
{ static bool convert(orxonox::Vector4* output, const std::string& input); };
- // std::string to Quaternion
+ /// std::string to Ogre::Quaternion conversion
template <> struct _UtilExport ConverterFallback<std::string, orxonox::Quaternion>
{ static bool convert(orxonox::Quaternion* output, const std::string& input); };
- // std::string to ColourValue
+ /// std::string to Ogre::ColourValue conversion
template <> struct _UtilExport ConverterFallback<std::string, orxonox::ColourValue>
{ static bool convert(orxonox::ColourValue* output, const std::string& input); };
@@ -151,7 +151,7 @@
// From and to Radian/Degree //
///////////////////////////////
- // From Radian
+ /// Delegates conversions from Radian to conversions from float
template <class ToType>
struct ConverterFallback<orxonox::Radian, ToType>
{
@@ -161,7 +161,7 @@
}
};
- // From Degree
+ /// Delegates conversions from Degree to conversions from float
template <class ToType>
struct ConverterFallback<orxonox::Degree, ToType>
{
@@ -171,7 +171,7 @@
}
};
- // To Radian
+ /// Delegates conversions to Radian to conversions to float
template <class FromType>
struct ConverterFallback<FromType, orxonox::Radian>
{
@@ -188,7 +188,7 @@
}
};
- // To Degree
+ /// Delegates conversions to Degree to conversions to float
template <class FromType>
struct ConverterFallback<FromType, orxonox::Degree>
{
Modified: code/branches/doc/src/libraries/util/OrxAssert.h
===================================================================
--- code/branches/doc/src/libraries/util/OrxAssert.h 2010-09-06 12:54:21 UTC (rev 7366)
+++ code/branches/doc/src/libraries/util/OrxAssert.h 2010-09-06 13:51:29 UTC (rev 7367)
@@ -40,8 +40,15 @@
#include <cassert>
#include "OutputHandler.h"
-// define an assert macro that can display a message
#ifndef NDEBUG
+/** Run time assertion like assert(), but with an embedded message.
+ at details
+ The message will be printed as error with COUT(1). <br>
+ You can use the same magic here as you can with \ref ThrowException
+ @code
+ OrxAssert(condition, "Text: " << number << " more text");
+ @endcode
+*/
#define OrxAssert(Assertion, ErrorMessage) \
Assertion ? ((void)0) : (void)(orxonox::OutputHandler::getOutStream(1) << ErrorMessage << std::endl); \
assert(Assertion)
Modified: code/branches/doc/src/libraries/util/OrxEnum.h
===================================================================
--- code/branches/doc/src/libraries/util/OrxEnum.h 2010-09-06 12:54:21 UTC (rev 7366)
+++ code/branches/doc/src/libraries/util/OrxEnum.h 2010-09-06 13:51:29 UTC (rev 7367)
@@ -26,12 +26,6 @@
*
*/
-/**
- at file
- at brief
- Declaration of the OrxEnum class.
-*/
-
#ifndef _OrxEnum_H__
#define _OrxEnum_H__
@@ -39,15 +33,33 @@
namespace orxonox
{
+ /** Lightweight enumeration class that can be extended at run time.
+ @details
+ The class accepts type int and also defines operator int(). Therefore
+ int and OrxEnum can be used interchangeably so you can extend the content
+ of the enumeration at run time by adding ints.
+ @par Declaring an OrxEnum
+ Write a struct that inherits OrxEnum and use some macros:
+ @code
+ struct MyEnum : OrxEnum<MyEnum>
+ {
+ OrxEnumConstructors(MyEnum);
+
+ static const int Value1 = -1;
+ static const int Value2 = 0;
+ static const int Value3 = Value2 + 10;
+ };
+ @endcode
+ */
template <class T>
struct OrxEnum
{
public:
OrxEnum() { }
- OrxEnum(int type) { type_ = type; }
+ OrxEnum(int type) { type_ = type; }
OrxEnum(const T& instance) { type_ = instance.type_; }
- operator int() { return type_; }
+ operator int() { return type_; }
T& operator =(int type) { type_ = type; return *this; }
bool operator <(const T& right) const { return (type_ < right.type_); }
bool operator >(const T& right) const { return (type_ > right.type_); }
@@ -58,6 +70,7 @@
};
}
+/// See orxonox::OrxEnum for more info
#define OrxEnumConstructors(enumName) \
enumName() { } \
enumName(int type) : OrxEnum<enumName>(type) { } \
Modified: code/branches/doc/src/libraries/util/TriBool.h
===================================================================
--- code/branches/doc/src/libraries/util/TriBool.h 2010-09-06 12:54:21 UTC (rev 7366)
+++ code/branches/doc/src/libraries/util/TriBool.h 2010-09-06 13:51:29 UTC (rev 7367)
@@ -34,6 +34,11 @@
// tolua_begin
namespace orxonox
{
+ /** Sort of a boolean value that also has state \c Dontcare
+ @remarks
+ Even though \c False has the value 0, both \c True and \c Dontcare have
+ a value other than 0. Keep that in mind when using TriBools in if statements.
+ */
namespace TriBool
{
enum Value
More information about the Orxonox-commit
mailing list