Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 6, 2010, 3:51:29 PM (14 years ago)
Author:
rgrieder
Message:

Added Doxygen documentation for ExprParser, MathConvert, OrxEnum, OrxAssert and TriBool.
Adjusted Doxygen documentation for Clock and Exception.

Location:
code/branches/doc/src/libraries/util
Files:
9 edited

Legend:

Unmodified
Added
Removed
  • code/branches/doc/src/libraries/util/Clock.cc

    r7331 r7367  
    4545    }
    4646
    47     /**
    48     @remarks
    49         Mind the types! Ogre::Timer::getMicroseconds() will return an unsigned
    50         long, which will eventually overflow. But if you use the subtraction of
    51         the current time minus the last time the timer gave us and sum these up to
    52         a 64 bit integer, we get the desired result. <br>
    53         Also mind that we don't have to store the last timer's time as unsigned long
    54         as well because (unsigned long)tickTime_ will do exactly that.
    55     */
    5647    void Clock::capture()
    5748    {
  • code/branches/doc/src/libraries/util/Clock.h

    r7331 r7367  
    4141        via Clock& references (for instance for the game tick). <br>
    4242        Precision: <br>
     43    @par Precision
    4344        The maximum precision is given by the Ogre::Timer and that is somewhere
    4445        in the microsecond range for both Windows and UNIX.
    45     @remarks
     46    @par Remarks for Usage on Windows
    4647        For proper functionality this class MUST be used in the same thread! <br>
    47         Further more it might be possible that the Ogre::Timer has a performance
    48         caveat on Windows because it will only capture the time on the same
    49         CPU core. Confining the main thread to one process could speed up the game.
    50         See command line argument 'limitToCPU'.
     48        Furthermore it might be possible that the Ogre::Timer has a performance
     49        caveat because it will only capture the time on the same CPU core.
     50        Confining the main thread to one process could speed up the game.
     51        See \ref cmdargspage "Ccommandline Argument" 'limitToCPU' (only on Windows)
    5152    */
    5253    class _UtilExport Clock
    5354    {
    5455    public:
    55         //! Starts the time at 0
     56        /// Starts the time at 0
    5657        Clock();
    5758        ~Clock();
    5859
    59         //! Internally captures the time and stays at that particular time
     60        /** Internally captures the time and stays at that particular time
     61        @remarks
     62            Mind the types! Ogre::Timer::getMicroseconds() will return an unsigned
     63            long, which will eventually overflow. But if you use the subtraction of
     64            the current time minus the last time the timer gave us and sum these up to
     65            a 64 bit integer, we get the desired result. <br>
     66            Also mind that we don't have to store the last timer's time as unsigned long
     67            as well because (unsigned long)tickTime_ will do exactly that.
     68        */
    6069        void capture();
    6170
    62         //! Returns the last captured absolute time in microseconds
     71        /// Returns the last captured absolute time in microseconds
    6372        unsigned long long getMicroseconds() const
    6473            { return tickTime_; }
    65         //! Returns the last captured absolute time in milliseconds
     74        /// Returns the last captured absolute time in milliseconds
    6675        unsigned long long getMilliseconds() const
    6776            { return tickTime_ / 1000; }
    68         //! Returns the last captured absolute time in seconds
     77        /// Returns the last captured absolute time in seconds
    6978        unsigned long getSeconds() const
    7079            { return static_cast<long> (tickTime_ / 1000000); }
    71         //! Returns the last captured absolute time in seconds as float
     80        /// Returns the last captured absolute time in seconds as float
    7281        float getSecondsPrecise() const
    7382            { return static_cast<float>(tickTime_ / 1000000.0f); }
    7483
    75         //! Returns the timespan in seconds between the last two calls to capture()
     84        /// Returns the timespan in seconds between the last two calls to capture()
    7685        float getDeltaTime() const
    7786            { return tickDtFloat_; }
    78         //! Returns the timespan in microseconds between the last two calls to capture()
     87        /// Returns the timespan in microseconds between the last two calls to capture()
    7988        long getDeltaTimeMicroseconds() const
    8089            { return tickDt_; }
     
    8897
    8998    private:
    90         //! Undefined
     99        /// Undefined
    91100        Clock(const Clock& instance);
    92101
    93         Ogre::Timer*       timer_;       //!< Ogre timer object
    94         unsigned long long tickTime_;    //!< Currently captured time
    95         long               tickDt_;      //!< Delta time in microseconds (cache value)
    96         float              tickDtFloat_; //!< Delta time in seconds (cache value)
     102        Ogre::Timer*       timer_;       ///< Ogre timer object
     103        unsigned long long tickTime_;    ///< Currently captured time
     104        long               tickDt_;      ///< Delta time in microseconds (cache value)
     105        float              tickDtFloat_; ///< Delta time in seconds (cache value)
    97106    };
    98107}
  • code/branches/doc/src/libraries/util/Exception.cc

    r7174 r7367  
    5353    { }
    5454
    55     /**
    56     @remarks
    57         The composed full description gets stored to fullDescription_. But for compliance
    58         with std::exception, this method has to be const. Hence fullDescription_ is declared
    59         as mutable.
    60     */
    6155    const std::string& Exception::getFullDescription() const
    6256    {
     
    8983    }
    9084
    91     //! Returns the error description
    9285    const char* Exception::what() const throw()
    9386    {
  • code/branches/doc/src/libraries/util/Exception.h

    r7297 r7367  
    3131@brief
    3232    Declaration of facilities to handle exceptions.
     33@details
     34    Any exception thrown should inherit from orxonox::Exception. There is a macro
     35    \ref CREATE_ORXONOX_EXCEPTION to create a new exception (you can find a list of
     36    available exceptions in the docs of this file). <br>
     37    Throwing exception is also very simple:
     38    @code
     39        ThrowException(General, "Something went wrong");
     40    @endcode
     41    (\c General is a type of exception, see docs of this file) <br>
     42    The exception will automatically contain information about file, line number
     43    and function name it occurred in. <br><br>
     44    There is also some magic you can do for numbers, etc.:
     45    @code
     46        ThrowException(General, "Error code: " << myInt << ". more info...");
     47    @endcode
     48    It works with an std::ostringstream, so you can feed it all sorts of values.
    3349*/
    3450
     
    4561namespace orxonox
    4662{
    47     /**
    48     @brief
    49         Base class for all exceptions (derived from std::exception).
     63    /** Base class for all exceptions (derived from std::exception).
    5064    @details
    5165        This class provides support for information about the file, the line
    52         and the function the error occured.
     66        and the function the error occurred.
     67    @see Exception.h
    5368    */
    5469    class _UtilExport Exception : public std::exception
     
    7489        //! Needed for compatibility with std::exception
    7590        virtual ~Exception() throw() { }
     91        //! Returns the error description
    7692        const char* what() const throw();
    7793
    78         //! Returns a full description with type, line, file and function
     94        /** Returns a full description with type, line, file and function
     95        @remarks
     96            The composed full description gets stored to fullDescription_. But for compliance
     97            with std::exception, this method has to be const. Hence fullDescription_ is declared
     98            as mutable.
     99        */
    79100        virtual const std::string& getFullDescription() const;
    80101        //! Returns the string name of the exception type
     
    107128    };
    108129
    109 //! Creates a new type of exception that inherits from tracker::Exception
     130//! Creates a new type of exception that inherits from orxonox::Exception
    110131#define CREATE_ORXONOX_EXCEPTION(ExceptionName)                                     \
    111132    class ExceptionName##Exception : public Exception                               \
     
    129150    // Creates all possible exception types.
    130151    // If you want to add a new type, simply copy and adjust a new line here.
    131 #ifndef DOXYGEN_SHOULD_SKIP_THIS
    132152    CREATE_ORXONOX_EXCEPTION(General);
    133153    CREATE_ORXONOX_EXCEPTION(FileNotFound);
     
    142162    CREATE_ORXONOX_EXCEPTION(NoGraphics);
    143163    CREATE_ORXONOX_EXCEPTION(AbortLoading);
    144 #endif
    145164
    146     /**
    147     @brief
    148         Helper function that forwards an exception and displays the message.
     165    /** Helper function that forwards an exception and displays the message.
    149166    @details
    150167        This is necessary because only when using 'throw' the objects storage is managed.
     
    158175    }
    159176
    160 /**
    161 @brief
    162     Throws an exception and logs a message beforehand.
     177/** Throws an exception and logs a message beforehand.
    163178@param type
    164179    Type of the exception as literal (General, Initialisation, etc.)
    165180@param description
    166181    Exception description as string
     182@see Exception.h
    167183*/
    168184#define ThrowException(type, description) \
  • code/branches/doc/src/libraries/util/ExprParser.h

    r6417 r7367  
    2828
    2929/**
    30   @file
    31   @brief Declaration of FloatParser
     30@file
     31@brief Declaration of FloatParser
    3232*/
    3333
     
    4242namespace orxonox
    4343{
     44    /** Parser for expressions like \c "3 * cos(5 + 4) / a" where \a a is a predeclared
     45        variable.
     46    @par Usage
     47        Using it is rather simple:
     48        @code
     49        std::string str("3 + 4");
     50        ExprParser expr;
     51        expr.parse(str);
     52        if (expr.getSuccess())
     53        {
     54            if (!expr.getRemains().empty())
     55            {
     56                COUT(2) << "Warning: Expression could not be parsed to the end! Remains: '" << expr.getRemains() << '\'' << std::endl;
     57            }
     58            double result = expr.getResult();
     59        }
     60        else
     61            COUT(1) << "Error: Cannot calculate expression: Parse error." << std::endl;
     62        @endcode
     63        getRemains() returns the expression after what could be parsed. For instance
     64        \c "2*3 text" will return \c "text" as remains.
     65    @details
     66        The implementation of this class is really old and sort of a trial for
     67        a first C++ class by Reto. That explains why it looks more like C than
     68        C++... Also some of the variable names are in German. <br>
     69        Explaining how it works exactly is probably not possible anymore, but it
     70        is based on recursively parsing the expression character by character.
     71        That much I can remember.
     72    @par Functions, operators and variables supported
     73        - Variables:
     74            - e
     75            - pi
     76        - Functions:
     77            - sin, asin, sinh, asinh
     78            - cos, acos, cosh, acosh
     79            - tan, atan, tanh, atanh
     80            - int, floor, ceil, abs, sign
     81            - pow, sqrt, exp, ln, log
     82            - mod, div
     83            - min, max
     84            - radians, degrees
     85        - Operators:
     86            - +, -, ! (unary)
     87            - +, -, *, /, %, ^, |, &, !, <, >, !=, <=, >=, =
     88    @note
     89        Operators may not be very consistent with C++ rules, but using the class
     90        for plus and minus should be perfectly ok.
     91    */
    4492    class _UtilExport ExprParser
    4593    {
  • code/branches/doc/src/libraries/util/MathConvert.h

    r6417 r7367  
    2828
    2929/**
    30     @file
    31     @brief
    32         Math conversion functions. Definitions are in Math.cc
     30@file
     31@brief
     32    Conversion functions for Math types like Ogre::Vector3 (definitions are in Math.cc)
    3333*/
    3434
     
    4646    ////////////////////
    4747
    48     // Vector2 to std::string
     48    /// Ogre::Vector2 to std::string conversion
    4949    template <>
    5050    struct ConverterExplicit<orxonox::Vector2, std::string>
     
    6262    };
    6363
    64     // Vector3 to std::string
     64    /// Ogre::Vector3 to std::string conversion
    6565    template <>
    6666    struct ConverterExplicit<orxonox::Vector3, std::string>
     
    7878    };
    7979
    80     // Vector4 to std::string
     80    /// Ogre::Vector4 to std::string conversion
    8181    template <>
    8282    struct ConverterExplicit<orxonox::Vector4, std::string>
     
    9494    };
    9595
    96     // Quaternion to std::string
     96    /// Ogre::Quaternion to std::string conversion
    9797    template <>
    9898    struct ConverterExplicit<orxonox::Quaternion, std::string>
     
    110110    };
    111111
    112     // ColourValue to std::string
     112    /// Ogre::ColourValue to std::string conversion
    113113    template <>
    114114    struct ConverterExplicit<orxonox::ColourValue, std::string>
     
    131131    ////////////////////
    132132
    133     // std::string to Vector2
     133    /// std::string to Ogre::Vector2 conversion
    134134    template <> struct _UtilExport ConverterFallback<std::string, orxonox::Vector2>
    135135    { static bool convert(orxonox::Vector2*     output, const std::string& input); };
    136     // std::string to Vector3
     136    /// std::string to Ogre::Vector3 conversion
    137137    template <> struct _UtilExport ConverterFallback<std::string, orxonox::Vector3>
    138138    { static bool convert(orxonox::Vector3*     output, const std::string& input); };
    139     // std::string to Vector4
     139    /// std::string to Ogre::Vector4 conversion
    140140    template <> struct _UtilExport ConverterFallback<std::string, orxonox::Vector4>
    141141    { static bool convert(orxonox::Vector4*     output, const std::string& input); };
    142     // std::string to Quaternion
     142    /// std::string to Ogre::Quaternion conversion
    143143    template <> struct _UtilExport ConverterFallback<std::string, orxonox::Quaternion>
    144144    { static bool convert(orxonox::Quaternion*  output, const std::string& input); };
    145     // std::string to ColourValue
     145    /// std::string to Ogre::ColourValue conversion
    146146    template <> struct _UtilExport ConverterFallback<std::string, orxonox::ColourValue>
    147147    { static bool convert(orxonox::ColourValue* output, const std::string& input); };
     
    152152    ///////////////////////////////
    153153
    154     // From Radian
     154    /// Delegates conversions from Radian to conversions from float
    155155    template <class ToType>
    156156    struct ConverterFallback<orxonox::Radian, ToType>
     
    162162    };
    163163
    164     // From Degree
     164    /// Delegates conversions from Degree to conversions from float
    165165    template <class ToType>
    166166    struct ConverterFallback<orxonox::Degree, ToType>
     
    172172    };
    173173
    174     // To Radian
     174    /// Delegates conversions to Radian to conversions to float
    175175    template <class FromType>
    176176    struct ConverterFallback<FromType, orxonox::Radian>
     
    189189    };
    190190
    191     // To Degree
     191    /// Delegates conversions to Degree to conversions to float
    192192    template <class FromType>
    193193    struct ConverterFallback<FromType, orxonox::Degree>
  • code/branches/doc/src/libraries/util/OrxAssert.h

    r6105 r7367  
    4141#include "OutputHandler.h"
    4242
    43 // define an assert macro that can display a message
    4443#ifndef NDEBUG
     44/** Run time assertion like assert(), but with an embedded message.
     45@details
     46    The message will be printed as error with COUT(1). <br>
     47    You can use the same magic here as you can with \ref ThrowException
     48    @code
     49        OrxAssert(condition, "Text: " << number << " more text");
     50    @endcode
     51*/
    4552#define OrxAssert(Assertion, ErrorMessage) \
    4653    Assertion ? ((void)0) : (void)(orxonox::OutputHandler::getOutStream(1) << ErrorMessage << std::endl); \
  • code/branches/doc/src/libraries/util/OrxEnum.h

    r5738 r7367  
    2727 */
    2828
    29 /**
    30 @file
    31 @brief
    32     Declaration of the OrxEnum class.
    33 */
    34 
    3529#ifndef _OrxEnum_H__
    3630#define _OrxEnum_H__
     
    4034namespace orxonox
    4135{
     36    /** Lightweight enumeration class that can be extended at run time.
     37    @details
     38        The class accepts type int and also defines operator int(). Therefore
     39        int and OrxEnum can be used interchangeably so you can extend the content
     40        of the enumeration at run time by adding ints.
     41    @par Declaring an OrxEnum
     42        Write a struct that inherits OrxEnum and use some macros:
     43        @code
     44        struct MyEnum : OrxEnum<MyEnum>
     45        {
     46            OrxEnumConstructors(MyEnum);
     47
     48            static const int Value1 = -1;
     49            static const int Value2 = 0;
     50            static const int Value3 = Value2 + 10;
     51        };
     52        @endcode
     53    */
    4254    template <class T>
    4355    struct OrxEnum
     
    4557        public:
    4658            OrxEnum() { }
    47             OrxEnum(int type)                  { type_ = type; }
     59            OrxEnum(int type)            { type_ = type; }
    4860            OrxEnum(const T& instance)   { type_ = instance.type_; }
    4961
    50             operator int()                     { return type_; }
     62            operator int()               { return type_; }
    5163            T& operator =(int type)      { type_ = type; return *this; }
    5264            bool operator <(const T& right) const { return (type_ < right.type_); }
     
    5971}
    6072
     73/// See orxonox::OrxEnum for more info
    6174#define OrxEnumConstructors(enumName)                        \
    6275enumName() { }                                               \
  • code/branches/doc/src/libraries/util/TriBool.h

    r6746 r7367  
    3535namespace orxonox
    3636{
     37    /** Sort of a boolean value that also has state \c Dontcare
     38    @remarks
     39        Even though \c False has the value 0, both \c True and \c Dontcare have
     40        a value other than 0. Keep that in mind when using TriBools in if statements.
     41    */
    3742    namespace TriBool
    3843    {
Note: See TracChangeset for help on using the changeset viewer.