From: Michael Andres <ma@suse.de>
Date: Tue, 25 Nov 2008 15:25:54 +0000 (+0000)
Subject: - Add CodePitfalls page to doc and mention TriBool there.
X-Git-Tag: BASE-SuSE-Code-11-Branch~48
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=12a30f53ccb7c9a4e042ac5a0a4a9f83dcc60f5d;p=platform%2Fupstream%2Flibzypp.git

- Add CodePitfalls page to doc and mention TriBool there.
---

diff --git a/doc/autoinclude/CodePitfalls.doc b/doc/autoinclude/CodePitfalls.doc
new file mode 100644
index 0000000..71d0cca
--- /dev/null
+++ b/doc/autoinclude/CodePitfalls.doc
@@ -0,0 +1,60 @@
+namespace zypp
+{
+/** \page CodePitfalls Code Pitfalls - Frequently made mistakes
+
+\section TriBoolCompare Comparing TriBool values
+
+  Comparing two \ref TriBool values is not as easy as it might look like,
+  because the \c TriBool::operator== and \c TriBool::operator!= return
+  a \ref TriBool.
+
+  For example  is <tt>(indeterminate==indeterminate)</tt> not \c true, but
+  \c indeterminate. That's why the following snippet does not do what the
+  author expected:
+
+  \code
+    // buggy option class
+    struct Option
+    {
+      public:
+        Option()
+          : _value( indeterminate )
+        {}
+
+        bool get() const
+        { return ( _value == indeterminate ) ? true : bool(_value); }
+
+        void set( bool new_r )
+        { _value = new_r; }
+
+      private:
+        tribool _value;
+    };
+  \endcode
+
+  You find that \c get() returns \c false as long as the option is unset,
+  and not \c true as the code suggests. That's because <tt>(_value==indeterminate)</tt>
+  returns \c indeterminate.
+
+  \note Always use \c indeterminate(_value) to test whether a TriBools value is \c indeterminate:
+
+  \code
+        bool get() const
+        { return indeterminate( _value ) ? true : bool(_value); }
+  \endcode
+
+  \code
+        tribool _value;
+        ...
+        if ( indeterminate( _value ) )
+        { ... }              // indeterminate
+        else if ( _value )
+        { ... }              // true
+        else
+        { ... }              // false
+  \endcode
+<HR>
+
+
+*/
+}