[Orxonox-commit 2670] r7375 - in code/branches/doc/src/libraries: core tools
landauf at orxonox.net
landauf at orxonox.net
Wed Sep 8 01:39:02 CEST 2010
Author: landauf
Date: 2010-09-08 01:39:02 +0200 (Wed, 08 Sep 2010)
New Revision: 7375
Modified:
code/branches/doc/src/libraries/core/BaseObject.h
code/branches/doc/src/libraries/core/ClassFactory.h
code/branches/doc/src/libraries/core/ConfigFileManager.h
code/branches/doc/src/libraries/core/ConfigValueContainer.h
code/branches/doc/src/libraries/core/Core.h
code/branches/doc/src/libraries/core/CoreIncludes.h
code/branches/doc/src/libraries/core/DynLib.h
code/branches/doc/src/libraries/core/DynLibManager.h
code/branches/doc/src/libraries/core/Game.h
code/branches/doc/src/libraries/core/GameMode.h
code/branches/doc/src/libraries/core/Identifier.h
code/branches/doc/src/libraries/core/Iterator.h
code/branches/doc/src/libraries/core/ObjectList.h
code/branches/doc/src/libraries/core/ObjectListBase.h
code/branches/doc/src/libraries/core/ObjectListIterator.h
code/branches/doc/src/libraries/core/OrxonoxClass.cc
code/branches/doc/src/libraries/core/OrxonoxClass.h
code/branches/doc/src/libraries/core/SmartPtr.h
code/branches/doc/src/libraries/core/Super.h
code/branches/doc/src/libraries/core/WeakPtr.h
code/branches/doc/src/libraries/tools/Timer.cc
code/branches/doc/src/libraries/tools/Timer.h
Log:
added documentation
Modified: code/branches/doc/src/libraries/core/BaseObject.h
===================================================================
--- code/branches/doc/src/libraries/core/BaseObject.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/BaseObject.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -34,7 +34,7 @@
/**
@file
@ingroup BaseObject
- @brief Definition of the BaseObject class.
+ @brief Declaration of BaseObject, the base class of all objects in Orxonox.
The BaseObject is the parent of all classes representing an instance in the game.
*/
Modified: code/branches/doc/src/libraries/core/ClassFactory.h
===================================================================
--- code/branches/doc/src/libraries/core/ClassFactory.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/ClassFactory.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -31,7 +31,7 @@
@ingroup Object Factory
@brief Definition and implementation of the ClassFactory class
- The ClassFactory is able to create new objects of a specific class.
+ The ClassFactory is able to create new objects of a specific class which creates objects.
*/
#ifndef _ClassFactory_H__
Modified: code/branches/doc/src/libraries/core/ConfigFileManager.h
===================================================================
--- code/branches/doc/src/libraries/core/ConfigFileManager.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/ConfigFileManager.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -29,7 +29,7 @@
/**
@file
@ingroup Config ConfigFile
- @brief Declaration of ConfigFileManager and its helper classes.
+ @brief Declaration of ConfigFileManager and its helper classes, used to load and save config files.
*/
#ifndef _ConfigFileManager_H__
Modified: code/branches/doc/src/libraries/core/ConfigValueContainer.h
===================================================================
--- code/branches/doc/src/libraries/core/ConfigValueContainer.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/ConfigValueContainer.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -29,7 +29,7 @@
/**
@file
@ingroup Config ConfigFile
- @brief Declaration of the ConfigValueContainer class.
+ @brief Declaration of the ConfigValueContainer class, caches a config-value.
The ConfigValueContainer class contains all needed information about a configurable variable:
- the name of the variable
Modified: code/branches/doc/src/libraries/core/Core.h
===================================================================
--- code/branches/doc/src/libraries/core/Core.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/Core.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -35,6 +35,7 @@
/**
@file
@ingroup Management CoreGame
+ @brief Declaration of the Core singleton which is used to configure the program basics.
*/
#ifndef _Core_H__
Modified: code/branches/doc/src/libraries/core/CoreIncludes.h
===================================================================
--- code/branches/doc/src/libraries/core/CoreIncludes.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/CoreIncludes.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -34,7 +34,7 @@
/**
@file
@ingroup Object Factory
- @brief Definition of macros for Identifiers
+ @brief Defines several very important macros used to register objects, create factories, and to work with identifiers.
Every class needs the @c RegisterObject(class) macro in its constructor. If the class is an interface
or the @c BaseObject itself, it needs the macro @c RegisterRootObject(class) instead.
Modified: code/branches/doc/src/libraries/core/DynLib.h
===================================================================
--- code/branches/doc/src/libraries/core/DynLib.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/DynLib.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -32,6 +32,7 @@
/**
@file
@ingroup Management CoreGame
+ @brief Declaration of DynLib which represents a dynamically loaded module.
*/
#ifndef _Core_DynLib_H__
@@ -65,7 +66,7 @@
namespace orxonox
{
- /** Resource holding data about a dynamic library.
+ /** %Resource holding data about a dynamic library.
@remarks
This class holds the data required to get symbols from
libraries loaded at run-time (i.e. from DLL's for so's)
@@ -73,8 +74,6 @@
Adrian Cearnãu (cearny at cearny.ro)
@since
27 January 2002
- @see
- Resource
*/
class _CoreExport DynLib
{
Modified: code/branches/doc/src/libraries/core/DynLibManager.h
===================================================================
--- code/branches/doc/src/libraries/core/DynLibManager.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/DynLibManager.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -32,6 +32,7 @@
/**
@file
@ingroup Management CoreGame
+ @brief Declaration of DynLibManager, used to load modules at runtime.
*/
#ifndef _Core_DynLibManager_H__
Modified: code/branches/doc/src/libraries/core/Game.h
===================================================================
--- code/branches/doc/src/libraries/core/Game.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/Game.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -30,7 +30,7 @@
@file
@ingroup Management CoreGame
@brief
- Declaration of Game Singleton.
+ Declaration of Game Singleton which is responsible for running the game.
*/
#ifndef _Game_H__
Modified: code/branches/doc/src/libraries/core/GameMode.h
===================================================================
--- code/branches/doc/src/libraries/core/GameMode.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/GameMode.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -29,7 +29,7 @@
/**
@file
@ingroup Management CoreGame
- @brief Declaration of the GameMode class.
+ @brief Declaration of the GameMode class which stores and returns the current mode of the game.
*/
#ifndef _GameMode_H__
Modified: code/branches/doc/src/libraries/core/Identifier.h
===================================================================
--- code/branches/doc/src/libraries/core/Identifier.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/Identifier.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -34,7 +34,7 @@
/**
@file
@ingroup Class Identifier
- @brief Declaration of Identifier, definition of ClassIdentifier<T>.
+ @brief Declaration of Identifier, definition of ClassIdentifier<T>; used to identify the class of an object.
@anchor IdentifierExample
Modified: code/branches/doc/src/libraries/core/Iterator.h
===================================================================
--- code/branches/doc/src/libraries/core/Iterator.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/Iterator.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -29,7 +29,7 @@
/**
@file
@ingroup Object ObjectList
- @brief Definition of the Iterator class.
+ @brief Definition of the Iterator class, used to iterate through object-lists.
@anchor IteratorExample
Modified: code/branches/doc/src/libraries/core/ObjectList.h
===================================================================
--- code/branches/doc/src/libraries/core/ObjectList.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/ObjectList.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -34,7 +34,7 @@
/**
@file
@ingroup Object ObjectList
- @brief Definition of the ObjectList class.
+ @brief Definition of the ObjectList class, a wrapper of ObjectListBase.
@ref orxonox::ObjectList "ObjectList<T>" is a wrapper of an @ref orxonox::ObjectListBase
"ObjectListBase" of class @a T. Use @ref orxonox::ObjectListIterator "ObjectListIterator<T>"
Modified: code/branches/doc/src/libraries/core/ObjectListBase.h
===================================================================
--- code/branches/doc/src/libraries/core/ObjectListBase.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/ObjectListBase.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -29,7 +29,7 @@
/**
@file
@ingroup Object ObjectList
- @brief Declaration of the ObjectListBase class.
+ @brief Declaration of the ObjectListBase class which stores all objects of each class.
orxonox::ObjectListBase is a double-linked list, used by @ref orxonox::Identifier "Identifiers"
to store all objects of a given class. Newly created objects are added to the list through the
Modified: code/branches/doc/src/libraries/core/ObjectListIterator.h
===================================================================
--- code/branches/doc/src/libraries/core/ObjectListIterator.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/ObjectListIterator.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -29,7 +29,7 @@
/**
@file
@ingroup Object ObjectList
- @brief Definition of the ObjectListIterator class.
+ @brief Definition of the ObjectListIterator class, used to iterate through object-lists.
@anchor ObjectListIteratorExample
Modified: code/branches/doc/src/libraries/core/OrxonoxClass.cc
===================================================================
--- code/branches/doc/src/libraries/core/OrxonoxClass.cc 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/OrxonoxClass.cc 2010-09-07 23:39:02 UTC (rev 7375)
@@ -28,7 +28,7 @@
/**
@file
- @brief Implementation of the OrxonoxClass Class.
+ @brief Implementation of OrxonoxClass.
*/
#include "OrxonoxClass.h"
Modified: code/branches/doc/src/libraries/core/OrxonoxClass.h
===================================================================
--- code/branches/doc/src/libraries/core/OrxonoxClass.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/OrxonoxClass.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -34,7 +34,7 @@
/**
@file
@ingroup Class OrxonoxClass
- @brief Declaration of the OrxonoxClass Class.
+ @brief Declaration of OrxonoxClass, the base class of all objects and interfaces in Orxonox.
All objects and interfaces of the game-logic (not the engine) are derived from OrxonoxClass.
It stores the Identifier and the MetaObjectList and has all needed functions to create and use the class-hierarchy.
Modified: code/branches/doc/src/libraries/core/SmartPtr.h
===================================================================
--- code/branches/doc/src/libraries/core/SmartPtr.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/SmartPtr.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -36,7 +36,7 @@
/**
@file
@ingroup Object SmartPtr
- @brief Definition of SmartPtr<T>.
+ @brief Definition of SmartPtr<T>, wraps a pointer to an object and keeps it alive.
@anchor SmartPtrExample
Modified: code/branches/doc/src/libraries/core/Super.h
===================================================================
--- code/branches/doc/src/libraries/core/Super.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/Super.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -34,7 +34,7 @@
/**
@file
@ingroup Class Super
- @brief Definition of all super-function related macros.
+ @brief Definition of all super-function related macros, used to call functions of the base class.
This file defines all macros needed to add a new "super-function". If you add
a super-function, you can call <tt>SUPER(myclass, functionname, arguments)</tt>
Modified: code/branches/doc/src/libraries/core/WeakPtr.h
===================================================================
--- code/branches/doc/src/libraries/core/WeakPtr.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/core/WeakPtr.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -31,7 +31,7 @@
/**
@file
@ingroup Object SmartPtr
- @brief Definition of WeakPtr<T>.
+ @brief Definition of WeakPtr<T>, wraps a pointer to an object.
@anchor WeakPtrExample
Modified: code/branches/doc/src/libraries/tools/Timer.cc
===================================================================
--- code/branches/doc/src/libraries/tools/Timer.cc 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/tools/Timer.cc 2010-09-07 23:39:02 UTC (rev 7375)
@@ -26,6 +26,11 @@
*
*/
+/**
+ @file
+ @brief Implementation of the Timer class.
+*/
+
#include "Timer.h"
#include <set>
@@ -44,7 +49,7 @@
static std::set<Timer*> delaytimerset;
/**
- @brief Calls a console command after 'delay' seconds.
+ @brief Console-command: Calls another console command after @a delay seconds.
@param delay The delay in seconds
@param command The console command
*/
@@ -59,8 +64,8 @@
}
/**
- @brief Executes the command.
- @param timer The timer to destroy after the command-execution
+ @brief Helper function for delay(), executes the command and destroys the timer.
+ @param timer The timer which called this function.
@param command The command to execute
*/
void executeDelayedCommand(Timer* timer, const std::string& command)
@@ -71,7 +76,7 @@
}
/**
- @brief Kills all delayed commands.
+ @brief Console-command: Kills all scheduled commands that were delayed using delay().
*/
void killdelays()
{
@@ -91,11 +96,11 @@
}
/**
- @brief Constructor: Initializes the Timer with given values.
- @param interval The timer-interval in seconds
- @param bLoop If true, the function gets called every 'interval' seconds
- @param executor A executor of the function to call
- @param bKillAfterCall If true, the timer will be deleted after the function was executed
+ @brief Constructor: Initializes and starts the timer, which will call an executor after some time.
+ @param interval The timer-interval in seconds
+ @param bLoop If true, the executor gets called every @a interval seconds
+ @param executor The executor that will be called
+ @param bKillAfterCall If true, the timer will be deleted after the executor was called
*/
Timer::Timer(float interval, bool bLoop, const ExecutorPtr& executor, bool bKillAfterCall)
{
@@ -120,7 +125,7 @@
}
/**
- @brief Executes the executor.
+ @brief Calls the executor and destroys the timer if requested.
*/
void Timer::run()
{
Modified: code/branches/doc/src/libraries/tools/Timer.h
===================================================================
--- code/branches/doc/src/libraries/tools/Timer.h 2010-09-07 23:01:23 UTC (rev 7374)
+++ code/branches/doc/src/libraries/tools/Timer.h 2010-09-07 23:39:02 UTC (rev 7375)
@@ -26,39 +26,51 @@
*
*/
-/*!
+/**
+ @defgroup Timer Timer
+ @ingroup Tools
+*/
+
+/**
@file
- @brief Definition and Implementation of the Timer class.
+ @ingroup Timer
+ @brief Declaration of the Timer class, used to call functions after a given time-interval.
- The Timer is a callback-object, calling a given function after a given time-interval.
+ @anchor TimerExample
+ Timer is a helper class that executes a function after a given amount of time.
+
Usage: <br>
header.h:
@code
- class ClassName
- {
- public:
- ClassName();
- void functionName();
- Timer myTimer;
- };
+ class MyClass
+ {
+ public:
+ MyClass();
+ void functionName();
+
+ private:
+ Timer myTimer;
+ };
@endcode
source.cc:
@code
- #include "core/command/Executor.h"
+ #include "core/command/Executor.h"
- ClassName::ClassName()
- {
- myTimer.setTimer(interval_in_seconds, bLoop, createExecutor(createFunctor(&ClassName::functionName, this)));
- }
+ MyClass::MyClass()
+ {
+ myTimer.setTimer(3, false, createExecutor(createFunctor(&ClassName::myFunction, this)));
+ }
- void ClassName::functionName()
- {
- whateveryouwant();
- something(else);
- }
+ void MyClass::myFunction()
+ {
+ COUT(0) << "Hello World" << std::endl;
+ }
@endcode
+
+ The code in this example prints "Hello World" to the console, 3 seconds after creating
+ an instance of MyClass.
*/
#ifndef _Timer_H__
@@ -76,7 +88,11 @@
void killdelays();
void executeDelayedCommand(Timer* timer, const std::string& command);
- //! The Timer is a callback-object, calling a given function after a given time-interval.
+ /**
+ @brief Timer is a helper class that executes a function after a given amount of time.
+
+ @see See @ref TimerExample "Timer.h" for an example.
+ */
class _ToolsExport Timer : public TimeFactorListener
{
public:
@@ -85,11 +101,11 @@
Timer(float interval, bool bLoop, const ExecutorPtr& executor, bool bKillAfterCall = false);
/**
- @brief Initializes the Timer with given values.
- @param interval The timer-interval in seconds
- @param bLoop If true, the function gets called every 'interval' seconds
- @param executor A executor of the function to call
- @param bKillAfterCall If true, the timer will be deleted after the function was executed
+ @brief Initializes and starts the timer, which will call an executor after some time.
+ @param interval The timer-interval in seconds
+ @param bLoop If true, the executor gets called every @a interval seconds
+ @param executor The executor that will be called
+ @param bKillAfterCall If true, the timer will be deleted after the executor was called
*/
void setTimer(float interval, bool bLoop, const ExecutorPtr& executor, bool bKillAfterCall = false)
{
@@ -104,34 +120,34 @@
void run();
- /** @brief Starts the Timer: Function-call after 'interval' seconds. */
+ /// Re-starts the Timer: The executor will be called after @a interval seconds.
inline void startTimer()
{ this->bActive_ = true; this->time_ = this->interval_; }
- /** @brief Stops the Timer. */
+ /// Stops the Timer.
inline void stopTimer()
{ this->bActive_ = false; this->time_ = this->interval_; }
- /** @brief Pauses the Timer - it will continue with the actual state if you unpause it. */
+ /// Pauses the Timer - it will continue with the actual state if you call unpauseTimer().
inline void pauseTimer()
{ this->bActive_ = false; }
- /** @brief Unpauses the Timer - continues with the given state. */
+ /// Unpauses the Timer - continues with the given state.
inline void unpauseTimer()
{ this->bActive_ = true; }
- /** @brief Returns true if the Timer is active (= not stoped, not paused). @return True = Time is active */
+ /// Returns true if the Timer is active (neither stoped nor paused).
inline bool isActive() const
{ return this->bActive_; }
- /** @brief Returns the remaining time until the Timer calls the function. @return The remaining time */
+ /// Returns the remaining time until the Timer calls the executor.
inline float getRemainingTime() const
{ return static_cast<float>(this->time_ / 1000000.0f); }
- /** @brief Gives the Timer some extra time. @param time The amount of extra time in seconds */
+ /// Increases the remaining time of the Timer by the given amount of time (in seconds).
inline void addTime(float time)
{ if (time > 0.0f) this->time_ += static_cast<long long>(time * 1000000.0f); }
- /** @brief Decreases the remaining time of the Timer. @param time The amount of time to remove */
+ /// Decreases the remaining time of the Timer by the given amount of time (in seconds)
inline void removeTime(float time)
{ if (time > 0.0f) this->time_ -= static_cast<long long>(time * 1000000.0f); }
- /** @brief Sets the interval of the Timer. @param interval The interval */
+ /// Changes the calling interval.
inline void setInterval(float interval)
{ this->interval_ = static_cast<long long>(interval * 1000000.0f); }
- /** @brief Sets bLoop to a given value. @param bLoop True = loop */
+ /// Defines if the timer call the executor every @a interval seconds or only once.
inline void setLoop(bool bLoop)
{ this->bLoop_ = bLoop; }
@@ -140,14 +156,14 @@
private:
void init();
- ExecutorPtr executor_; //!< The executor of the function that should be called when the time expires
+ ExecutorPtr executor_; //!< The executor of the function that will be called when the time expires
long long interval_; //!< The time-interval in micro seconds
- bool bLoop_; //!< If true, the function gets called every 'interval' seconds
- bool bActive_; //!< If true, the Timer ticks and calls the function if the time's up
- bool bKillAfterCall_; //!< If true the timer gets deleted after it called the function
+ bool bLoop_; //!< If true, the executor gets called every @a interval seconds
+ bool bActive_; //!< If true, the Timer ticks and calls the executor if the time's up
+ bool bKillAfterCall_; //!< If true the timer gets deleted after it expired and called the executor
- long long time_; //!< Internal variable, counting the time till the next function-call
+ long long time_; //!< Internal variable, counting the time untill the next executor-call
};
}
More information about the Orxonox-commit
mailing list