From 1ce55fb881197d5cdac5c9c36f9ed6918c64c70d Mon Sep 17 00:00:00 2001
From: Jan Kupec <jkupec@suse.cz>
Date: Fri, 22 Feb 2008 14:48:20 +0000
Subject: [PATCH] - comments

---
 src/output/Out.h       | 10 ++++++----
 src/output/OutNormal.h | 16 ++++++++++++++++
 src/output/xmlout.rnc  |  2 +-
 3 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/src/output/Out.h b/src/output/Out.h
index 212f394..bdd53aa 100644
--- a/src/output/Out.h
+++ b/src/output/Out.h
@@ -58,7 +58,7 @@ public:
   virtual void info(const std::string & msg, Verbosity verbosity = NORMAL, Type mask = TYPE_ALL) = 0;
 
   /**
-   * Show warning.
+   * Show a warning.
    * 
    * \param msg       The warning message to be displayed.
    * \param verbosity Minimal level o verbosity in which the message will be
@@ -71,12 +71,14 @@ public:
    *                  types of output. 
    */
   virtual void warning(const std::string & msg, Verbosity verbosity = NORMAL, Type mask = TYPE_ALL) = 0;
-  
+
   /**
    * Show an error message and an optional hint.
    * 
-   * \param problem_desc
-   * \param hint
+   * An error message should be shown regardless of the verbosity level.
+   * 
+   * \param problem_desc Problem description (what happend)
+   * \param hint         Hint for the user (what to do, or explanation)
    */
   virtual void error(const std::string & problem_desc, const std::string & hint = "") = 0;
   
diff --git a/src/output/OutNormal.h b/src/output/OutNormal.h
index 3bc8605..dad839f 100644
--- a/src/output/OutNormal.h
+++ b/src/output/OutNormal.h
@@ -10,8 +10,24 @@ public:
   virtual ~OutNormal();
 
 public:
+  /**
+   * Prints \a msg to the standard output and appends a newline.
+   *
+   *  \see Out::info()
+   */
   virtual void info(const std::string & msg, Verbosity verbosity = NORMAL, Type mask = TYPE_ALL);
+
+  /**
+   * Prints \a msg prepended with <tt>"Warning: "</tt> to the standard output
+   * and appends a newline.
+   * 
+   * \see Out::warning
+   */
   virtual void warning(const std::string & msg, Verbosity verbosity = NORMAL, Type mask = TYPE_ALL);
+  
+  /**
+   * 
+   */
   virtual void error(const std::string & problem_desc, const std::string & hint = "");
   virtual void error(const zypp::Exception & e,
              const std::string & problem_desc,
diff --git a/src/output/xmlout.rnc b/src/output/xmlout.rnc
index 1bddc68..0ab1151 100644
--- a/src/output/xmlout.rnc
+++ b/src/output/xmlout.rnc
@@ -61,7 +61,7 @@ download-progress-done =
 message-element =
   element message {
     attribute id { xsd:string }
-    attribute type { "info" | "warning" | "error" },
+    attribute type { "info" | "warning" | "error" }, # considering yet another type "result", maybe a separate <result> element 
     text
   }
 
-- 
2.7.4