Changeset 8848 for code/branches/output/src/libraries/util/Output.h

Timestamp:

Aug 21, 2011, 4:04:54 PM (14 years ago)

Author:

landauf

Message:

added documentation and some comments

File:

• code/branches/output/src/libraries/util/Output.h (modified) (4 diffs)

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

@@ -27 +27 @@
  */
 
+/**
+    @defgroup Output Output system
+    @ingroup Util
+*/
+
+/**
+    @file
+    @ingroup Output
+    @brief Defines the helper function orxout() and includes all necessary headers to use the output system.
+
+    The output system is used to write output to the console, the logfile, and
+    other instances of orxonox::OutputListener. Each line of output is assigned
+    a level and a context. The level defines the type and importance of a
+    message, e.g. if it's a fatal error or just some internal information.
+    The context defines to which part of the program the output belongs.
+    Levels and contexts are defined in OutputDefinitions.h
+
+    Each orxonox::OutputListener can define a mask of desired levels and
+    contexts, to receive only a part of the output. A derivative of
+    orxonox::BaseWriter is able to define these masks through config values
+    and to filter specific subcontexts.
+
+    @attention
+    A message sent to the output system MUST end with "endl" or the message
+    won't be flushed.
+
+    @code
+    orxout() << "Debug output" << endl;
+    orxout(user_info) << "Orxonox version 1.2.3" << endl;
+    orxout(internal_status, context::input) << "Loading joystick" << endl;
+    @endcode
+*/
+
 #ifndef _Output_H__
 #define _Output_H__
@@ -38 +71 @@
     using std::endl;
 
+    /**
+        @brief This helper function returns a reference to a commonly used
+        instance of OutputStream.
+
+        It can be used like std::cout except that it is a function. You can
+        pass level and context of the following output as function arguments.
+    */
     inline OutputStream& orxout(OutputLevel level = level::debug_output, const OutputContextContainer& context = context::undefined())
     {
@@ -45 +85 @@
     }
 
+    /**
+        @brief Shortcut for orxout() to allow passing contexts directly as
+        functions without using "()".
+
+        @code
+        orxout(user_info, context::example) << "Hello World" << endl; // calls this function
+        orxout(user_info, context::example()) << "Hello World" << endl; // calls the other orxout function
+        @endcode
+    */
     inline OutputStream& orxout(OutputLevel level, OutputContextFunction context)
     {
@@ -53 +102 @@
     inline __DEPRECATED__(OutputStream& COUT(int level));
 
+    /**
+        @brief Writes output to the orxonox console. This function is deprecated, please use orxout()
+        @note The output level argument is ignored since it's not supported anymore. See orxout() for the new output levels.
+        @deprecated This function is deprecated. Use orxout() instead.
+    */
     inline OutputStream& COUT(int)
     {