Changeset 8853 for code/branches/output/src/libraries/util/output/BaseWriter.h

Timestamp:

Aug 21, 2011, 11:18:20 PM (14 years ago)

Author:

landauf

Message:

documented the remaining code of the output system
created a build unit for the output system

File:

• code/branches/output/src/libraries/util/output/BaseWriter.h (modified) (5 diffs)

code/branches/output/src/libraries/util/output/BaseWriter.h

@@ -27 +27 @@
  */
 
+/**
+    @file
+    @ingroup Output
+    @brief Declaration of the BaseWriter class, the base of all output writers.
+*/
+
 #ifndef _BaseWriter_H__
 #define _BaseWriter_H__
@@ -35 +41 @@
 namespace orxonox
 {
+    /**
+        @brief BaseWriter is an output listener and makes the accepted output levels and contexts configurable.
+
+        All output writers like ConsoleWriter and LogWriter are inherited from
+        this class. BaseWriter itself inherits from SubcontextOutputListener.
+        It adds helper functions to configure the accepted levels and contexts.
+
+        The levels are not fully configurable, only the "max" form is allowed
+        (which means that it's only possible to define a maximum level, not
+        the full mask).
+
+        Contexts are defined by a vector of strings, each context is defined
+        by it's name. Sub-contexts have the form \a "main-name::sub-name", i.e.
+        their name is concatenated with :: in between.
+
+        Each instance of BaseWriter needs a name to generate distinguishable
+        config values.
+
+        Received output messages are split into lines and sent line by line to
+        the virtual printLine() function. Each line has a prepended prefix
+        which describes the level and context of the output.
+    */
     class _UtilExport BaseWriter : public SubcontextOutputListener
     {
@@ -44 +72 @@
             void setAdditionalContextsLevelMax(OutputLevel max);
 
+            /// @brief Returns the name of this instance.
             const std::string& getName() const
                 { return this->name_; }
 
+            /// Config value, used to define the maximum output level (independent of contexts)
             int configurableMaxLevel_;
+            /// @brief Returns the name of the config value which defines the maximum output level (independent of contexts).
             inline std::string getConfigurableMaxLevelName() const
                 { return this->name_ + "Level"; }
 
+            /// Config value, used to define the maximum output level of additional context
             int configurableAdditionalContextsMaxLevel_;
+            /// @brief Returns the name of the config value which defines the maximum output level of additional context.
             inline std::string getConfigurableAdditionalContextsMaxLevelName() const
                 { return this->name_ + "AdditionalContextsLevel"; }
 
+            /// Config vector, used to define the additional contexts (and sub-contexts)
             std::vector<std::string> configurableAdditionalContexts_;
+            /// @brief Returns the name of the config vector which defines the additional contexts (and sub-contexts)
             inline std::string getConfigurableAdditionalContextsName() const
                 { return this->name_ + "AdditionalContexts"; }
@@ -63 +98 @@
             void changedConfigurableAdditionalContexts();
 
+            /// Returns the (static) name of the section wherein the config-values are defined.
             static inline std::string getConfigurableSectionName()
                 { return "Output"; }
@@ -70 +106 @@
 
         private:
-            virtual void printLine(const std::string& line, OutputLevel level) = 0;
+            virtual void printLine(const std::string& line, OutputLevel level) = 0; ///< Pure virtual function, gets called for each line of output together with a prefix which describes level and context of the output.
 
-            void setLevelRange(OutputLevel min, OutputLevel max);
-            void setLevelMask(OutputLevel mask);
+            void setLevelRange(OutputLevel min, OutputLevel max);                   ///< Inherited function, overwritten as private because it is not supported by the config-value
+            void setLevelMask(OutputLevel mask);                                    ///< Inherited function, overwritten as private because it is not supported by the config-value
 
-            void setAdditionalContextsLevelRange(OutputLevel min, OutputLevel max);
-            void setAdditionalContextsLevelMask(OutputLevel mask);
+            void setAdditionalContextsLevelRange(OutputLevel min, OutputLevel max); ///< Inherited function, overwritten as private because it is not supported by the config-value
+            void setAdditionalContextsLevelMask(OutputLevel mask);                  ///< Inherited function, overwritten as private because it is not supported by the config-value
 
-            std::string name_;
+            std::string name_; ///< The name of this instance, used to generate unique config-values
     };
 }