Changeset 7484 for code/trunk

Timestamp:

Sep 23, 2010, 1:00:42 PM (14 years ago)

Author:

dafrick

Message:

Doing some documentation.

Location:

code/trunk

Files:

• doc/api/Groups.dox (modified) (1 diff)
• src/modules/notifications/Notification.cc (modified) (2 diffs)
• src/modules/notifications/Notification.h (modified) (2 diffs)
• src/modules/notifications/NotificationDispatcher.cc (modified) (2 diffs)
• src/modules/notifications/NotificationDispatcher.h (modified) (2 diffs)
• src/modules/notifications/NotificationManager.cc (modified) (3 diffs)
• src/modules/notifications/NotificationManager.h (modified) (3 diffs)
• src/modules/notifications/NotificationQueue.cc (modified) (1 diff)
• src/modules/notifications/NotificationQueue.h (modified) (2 diffs)
• src/modules/notifications/dispatchers/CommandNotification.cc (modified) (1 diff)
• src/modules/notifications/dispatchers/CommandNotification.h (modified) (2 diffs)
• src/modules/notifications/dispatchers/SimpleNotification.h (modified) (1 diff)
• src/modules/objects/Script.h (modified) (1 diff)
• src/modules/questsystem/QuestEffectBeacon.cc (modified) (1 diff)
• src/modules/questsystem/QuestManager.h (modified) (1 diff)
• src/orxonox/interfaces/NotificationListener.h (modified) (3 diffs)

code/trunk/doc/api/Groups.dox

@@ -336 +336 @@
     @section SampleQuest Sample quest
     To get your head around all of this and see some of the things mentioned here in action you might want to check out the "The Tale of Princess Aeryn"-Quest (Levelfile: princessaeryn.oxw) in the level-folder.
-
+*/
+
+/**
     @defgroup QuestEffects Effects
     @ingroup Questsystem

code/trunk/src/modules/notifications/Notification.cc

@@ -50 +50 @@
         RegisterRootObject(Notification);
         this->initialize();
-        this->registerVariables();
     }
 
@@ -122 +121 @@
     bool Notification::setMessage(const std::string & message)
     {
-        if(this->isSent()) //!< The message cannot be changed if the message has already been sent.
+        if(this->isSent()) // The message cannot be changed if the message has already been sent.
             return false;
         this->message_ = message;

code/trunk/src/modules/notifications/Notification.h

@@ -47 +47 @@
     /**
     @brief
-        A Notification is a short message used to inform the player about something that just happened. A Notification can be sent from any part of orxonox and is then displayed in the proper NotificationQueue (depending on which senders the specific NotificationQueue accepts).
+        A Notification is a short message used to inform the player about something that just happened. A Notification can be sent from any part of orxonox and is then displayed in the proper @ref orxonox::NotificationQueue "NotificationQueue" (depending on which senders the specific @ref orxonox::NotificationQueue "NotificationQueue" accepts).
     @author
         Damian 'Mozork' Frick
@@ -83 +83 @@
             bool sent_; //!< Whether Notification has been sent, if so it cannot be changed.
 
-            void initialize(void);
-            void registerVariables(void);
+            void initialize(void); //!< Registers the object and sets some default values.
 
     };

code/trunk/src/modules/notifications/NotificationDispatcher.cc

@@ -93 +93 @@
     }
 
+    /**
+    @brief
+        Registers variables for synchronisation.
+    */
     void NotificationDispatcher::registerVariables(void)
     {
@@ -113 +117 @@
         else if(GameMode::isServer())
         {
+            //TODO: This may fail if the object has not been synchronized, yet.
             callMemberNetworkFunction(NotificationDispatcher, dispatch, this->getObjectID(), clientId, clientId);
         }

code/trunk/src/modules/notifications/NotificationDispatcher.h

@@ -47 +47 @@
     /**
     @brief
-        A NotificationDispatcher is an entity that, upon being triggered, dispatches (or sends) a specified Notification.
+        A NotificationDispatcher is an entity that, upon being triggered, dispatches (or sends) a specified @ref orxonox::Notification "Notification".
+
+        Its standard usage is:
+        @code
+        <NotificationDispatcher>
+            <events>
+                <trigger>
+                    <PlayerTrigger />
+                </trigger>
+            </event>
+        </NotificationDispatcher>
+        @endcode
+        But keep in mind, that NotificationDispatcher is an abstract class and in this example @ref orxonox::PlayerTrigger "PlayerTrigger" stands for any event that is caused by a @ref orxonox::PlayerTrigger "PlayerTrigger", so instead of @ref orxonox::PlayerTrigger "PlayerTrigger", there could be a @ref orxonox::DistanceTrigger "DistanceTrigger", or a @ref orxonox::DistanceMultiTrigger "DistanceMutliTrigger", or even an @ref orxonox::EventListener "EventListener" that waits for an event coming from any kind of @ref orxonox::PlayerTrigger "PlayerTrigger".
     @author
         Damian 'Mozork' Frick
@@ -73 +85 @@
             std::string sender_; //!< The name of the sender of the Notification dispatched by this NotificationDispatcher.
 
-           void registerVariables(void);
+            void registerVariables(void); //!< Register some variables for synchronisation.
 
             /**

code/trunk/src/modules/notifications/NotificationManager.cc

@@ -60 +60 @@
     ManageScopedSingleton(NotificationManager, ScopeID::Graphics, false);
 
+    // Setting console command to enter the edit mode.
     SetConsoleCommand("enterEditMode", &NotificationManager::enterEditMode);
 
@@ -106 +107 @@
     }
 
+    /**
+    @brief
+        Sends a Notification with the specified message to the specified client from the specified sender.
+    @param message
+        The message that should be sent.
+    @param clientId
+        The id of the client the notification should be sent to.
+    @param sender
+        The sender that sent the notification.
+    */
     /*static*/ void NotificationManager::sendNotification(const std::string& message, unsigned int clientId, const std::string& sender)
     {
+        // If we're in standalone mode or we're already no the right client we create and send the Notification.
         if(GameMode::isStandalone() || Host::getPlayerID() == clientId)
         {
@@ -113 +125 @@
             notification->send(sender);
         }
+        // If we're on the server (and the server is not the intended recipient of the Notification) we send it over the network.
         else if(GameMode::isServer())
         {

code/trunk/src/modules/notifications/NotificationManager.h

@@ -50 +50 @@
     /**
     @brief
-        The Singleton NotificationManager functions as a gateway between Notifications and NotificationListeners.
-        It receives, organizes Notifications and the redistributes them to the specific NotificationListeners.
+        The Singleton NotificationManager functions as a gateway between @ref orxonox::Notification "Notifications" and @ref orxonox::NotificationListener "NotificationListeners".
+        It receives, organizes @ref orxonox::Notification "Notifications" and the redistributes them to the specific @ref orxonox::NotificationListener "NotificationListeners".
+        It also provides a static function to send @ref orxonox::Notification "Notifications" and works as a liaison between the @ref orxonox>>NotificationQueue "NotificationQueues" and the GUI that displays notification, called NotificationLayer.
     @author
         Damian 'Mozork' Frick
@@ -65 +66 @@
             virtual void preDestroy(void); //!< Is called before the object is destroyed.
 
+            /**
+            @brief Get the instance of the NotificationManager Singleton.
+            @return Returns a reference to the NotificationManager.
+            */
             static NotificationManager& getInstance() { return Singleton<NotificationManager>::getInstance(); } // tolua_export
 
@@ -70 +75 @@
             static const std::string NONE; //!< Static string to indicare a sender that sends to no specific NotificationListener.
 
+            //! Sends a Notification with the specified message to the specified client from the specified sender.
             static void sendNotification(const std::string& message, unsigned int clientId, const std::string& sender = NotificationManager::NONE);
 

code/trunk/src/modules/notifications/NotificationQueue.cc

@@ -52 +52 @@
         Constructor. Creates and initializes the object.
     @param name
-        The name of the new NotificationQueue.
+        The name of the new NotificationQueue. It needs to be unique
     @param senders
         The senders that are targets of this NotificationQueue, i.e. the names of senders whose Notifications this NotificationQueue displays.

code/trunk/src/modules/notifications/NotificationQueue.h

@@ -54 +54 @@
     struct NotificationContainer
     {
-        Notification* notification; //!< The Notification displayed.
-        time_t time; //!< The time the Notification was sent and thus first displayed.
+        Notification* notification; // The Notification displayed.
+        time_t time; // The time the Notification was sent and thus first displayed.
     };
 
@@ -61 +61 @@
     struct NotificationContainerCompare {
         bool operator() (const NotificationContainer* const & a, const NotificationContainer* const & b) const
-            { return a->time < b->time; } //!< Ordered by time.
+            { return a->time < b->time; } // Ordered by time.
     };
 
     /**
     @brief
-        Displays Notifications from specific senders.
+        Displays @ref orxonox::Notification "Notifications" from specific senders.
+
+        There are quite some parameters that influence the behaviour of the NotificationQueue:
+        - 'name': The name of the NotificationQueue. It needs to be unique.
+        - 'senders': The senders that are targets of this NotificationQueue, i.e. the names of senders whose Notifications this NotificationQueue displays.
+        - 'size': The size of the NotificationQueue, it specifies how many @ref orxonox::Notification "Notifications" are displayed at once at the most.
+        - 'displayTime': The time a @ref orxonox::Notification "Notification" is displayed with this NotificationQueue.
     @author
         Damian 'Mozork' Frick

code/trunk/src/modules/notifications/dispatchers/CommandNotification.cc

@@ -80 +80 @@
     }
 
+    /**
+    @brief
+        Register some variables for synchronisation.
+    */
     void CommandNotification::registerVariables(void)
     {

code/trunk/src/modules/notifications/dispatchers/CommandNotification.h

@@ -47 +47 @@
         This class implements a method of displaying a Notification with information to an input command and the key the command is mapped to.
         The message that is displayed is a string made out uf the concatenation of the preMessage, the key the specified command is mapped to and the postMessage.
+
+        In use it would like this:
+        @code
+        <CommandNotification preMessage="Please press " command="someCommand" postMessage=" to do something." >
+            <events>
+                <trigger>
+                    <PlayerTrigger />
+                </trigger>
+            </events>
+        </CommandNotification>
+        @endcode
+        Upon being triggered this would display the @ref orxonox::Notification "Notification" "Please press {the binding of the specified command} to do something".
+        For more information on what can be used for @code <PlayerTrigger /> @endcode see the @ref orxonox::NotificationDispatcher "NotificationDispatcher" documentation.
     @author
         Damian 'Mozork' Frick
@@ -86 +99 @@
             std::string postMessage_; //!< The last part of the displayed message.
 
-            void registerVariables(void);
+            void registerVariables(void); //!< Register some variables for synchronisation.
 
             /**

code/trunk/src/modules/notifications/dispatchers/SimpleNotification.h

@@ -46 +46 @@
     @brief
         The SimpleNotification class enables the sending of (in XML) predefined Notifications upon some kind of triggering event.
+
+        In use it would like this:
+        @code
+        <SimpleNotification message="some message..." >
+            <events>
+                <trigger>
+                    <PlayerTrigger />
+                </trigger>
+            </events>
+        </SimpleNotification>
+        @endcode
+        For more information on what can be used for @code <PlayerTrigger /> @endcode see the @ref orxonox::NotificationDispatcher "NotificationDispatcher" documentation.
     @author
         Damian 'Mozork' Frick

code/trunk/src/modules/objects/Script.h

@@ -81 +81 @@
     @author
         Benjamin Knecht
+    @author
         Damian 'Mozork' Frick
     */

code/trunk/src/modules/questsystem/QuestEffectBeacon.cc

@@ -52 +52 @@
         Constructor. Registers the object and initializes defaults.
     */
-    //TODO: Make just BaseObject?
     QuestEffectBeacon::QuestEffectBeacon(BaseObject* creator) : StaticEntity(creator)
     {

code/trunk/src/modules/questsystem/QuestManager.h

@@ -50 +50 @@
     @brief
         Is a Singleton and manages @ref orxonox::Quest "Quests", by registering every @ref orxonox::Quest "Quest" / @ref orxonox::QuestHint "QuestHint" (through registerX()) and making them globally accessible (through findX()).
-        @ref orxonox::Quest "Quests" (and @ref orxonox::QuestHint 2) are registered in the QuestManager with their id, and can be accessed in the same way.
+        @ref orxonox::Quest "Quests" (and @ref orxonox::QuestHint "QuestHints") are registered in the QuestManager with their id, and can be accessed in the same way.
     @author
         Damian 'Mozork' Frick

code/trunk/src/orxonox/interfaces/NotificationListener.h

@@ -28 +28 @@
 
 /**
-    @file
+    @file NotificationListener.h
     @brief Definition of the NotificationListener class.
+    @ingroup Notifications
 */
 
@@ -52 +53 @@
     @brief
         NotificationListener interface.
+
+        The NotificationListener interface presents a means to being informed when @ref orxonox::Notification "Notifications" in the target set of this NotificationListener change. (e.g. @ref orxonox::Notification "Notifications" were added or removed)
+        When inheriting from a NotificationListener it is important to register (in the constructor) and unregister (in the destructor) it to and from the @ref orxonox::NotificationManager "NotificationManager".
     @author
         Fabian 'x3n' Landau
     */
+    //TODO: Needed? Remove or move some NotificationQueue things over here.
     class _OrxonoxExport NotificationListener : virtual public OrxonoxClass
     {
@@ -61 +66 @@
             virtual ~NotificationListener() {}
 
-            virtual const std::set<std::string> & getTargetsSet() = 0;
+            /**
+            @brief Get the senders that are targets of this NotificationListener.
+            @return Returns the set of senders that are targets of this NotificationListener.
+            */
+            virtual const std::set<std::string> & getTargetsSet(void) = 0;
+
+            /**
+            @brief Updates the whole NotificationListener.
+                   This is called by the @ref orxonox::NotificationManager "NotificationManager" when the @ref orxonox::Notification "Notifications" have changed so much, that the NotificationListener may have to re-initialize his operations.
+            */
             virtual void update(void) = 0;
+            /**
+            @brief Updates the NotificationListener, when a new Notification has come in at the specified time.
+            @param notification A pointer to the @ref orxonox::Notification "Notification".
+            @param time The time the @ref orxonox::Notification "Notification" has come in.
+            */
             virtual void update(Notification* notification, const std::time_t & time) = 0;
     };