reviewed docs up to extra section. renamed DOXYGEN macro with BOOST_CONTRACT_DETAIL_DOXYGEN

example/features/ifdef_audit.cpp

@@ -23,34 +23,43 @@
 #define CONTRACT_ASSERT_AXIOM(cond) BOOST_CONTRACT_ASSERT(true || (cond))
 
 template<typename RandomIter, typename T>
-bool random_binary_search(RandomIter first, RandomIter last, T const& value) {
+RandomIter random_binary_search(RandomIter first, RandomIter last,
+        T const& value) {
+    RandomIter result;
     boost::contract::check c = boost::contract::function()
         .precondition([&] {
             BOOST_CONTRACT_ASSERT(first <= last);
             // Expensive O(n) assertion so marked "audit".
             CONTRACT_ASSERT_AUDIT(std::is_sorted(first, last));
         })
+        .postcondition([&] {
+            if(result != last) BOOST_CONTRACT_ASSERT(*result == value);
+        })
     ;
 
     /* ... */
 //]
 
-    while(first < last) {
-        RandomIter middle = first + ((last - first) >> 1);
-        BOOST_CONTRACT_CHECK(*first <= *middle || value < *middle ||
+    RandomIter being = first, end = last;
+    while(begin < end) {
+        RandomIter middle = begin + ((end - begin) >> 1);
+        BOOST_CONTRACT_CHECK(*begin <= *middle || value < *middle ||
                 *middle < value);
         
-        if(value < *middle) last = middle;
-        else if(value > *middle) first = middle + 1;
-        else return true;
+        if(value < *middle) end = middle;
+        else if(value > *middle) begin = middle + 1;
+        else return result = middle;
     }
-    return false;
+    return result = last;
 }
 
 int main() {
-    std::vector<char> i(3);
-    i[0] = 'a'; i[1] = 'b'; i[2] = 'c';
-    assert(random_binary_search(i.begin(), i.end(), 'b'));
+    std::vector<char> v(3);
+    v[0] = 'a'; v[1] = 'b'; v[2] = 'c';
+    std::vector<char>::iterator i = random_binary_search(v.begin(), v.end(),
+            'b');
+    assert(i != v.end());
+    assert(*i == 'b');
     return 0;
 }