docs: updated decorators doc to match develop

doc/examples.qbk

@@ -9,13 +9,12 @@
 [section:boost_test_examples Examples]
 
 
-[bt_example_page 01..Manual declaration of a free test function]
+[bt_example_page example01..Manual declaration of a free test function]
 
-[bt_example_page 02..Manual declaration of a test in a member function]
+[bt_example_page example02..Manual declaration of a test in a member function]
 
-[bt_example_page 03..Manual declaration of a test in a member function (2)]
-
-[bt_example_page 68..Dataset generating a Fibonacci sequence]
+[bt_example_page example03..Manual declaration of a test in a member function (2)]
 
+[bt_example_page example68..Dataset generating a Fibonacci sequence]
 
 [endsect] [/ section examples]

doc/examples/example70_decorators.cpp

@@ -6,45 +6,25 @@
 //  See http://www.boost.org/libs/test for the library home page.
 
 //[example_code
-#define BOOST_TEST_MODULE example
+#define BOOST_TEST_MODULE example70
 #include <boost/test/unit_test.hpp>
-
 namespace utf = boost::unit_test;
 
+BOOST_TEST_DECORATOR(
+  + utf::label("trivial")
+)
 BOOST_AUTO_TEST_CASE( test_case1 )
 {
   BOOST_TEST(true);
 }
 
 BOOST_TEST_DECORATOR(
-  + utf::enable_if(false)
+  + utf::label("trivial")
+  + utf::label("cmp")
+  + utf::description("testing equality of ones")
 )
 BOOST_AUTO_TEST_CASE( test_case2 )
 {
-  BOOST_TEST(false);
-}
-
-BOOST_TEST_DECORATOR(
-  + utf::depends_on("test_case1")
-)
-BOOST_AUTO_TEST_CASE( test_case3 )
-{
-  BOOST_TEST(false);
-}
-
-BOOST_TEST_DECORATOR(
-  + utf::depends_on("test_case3")
-)
-BOOST_AUTO_TEST_CASE( test_case4 )
-{
-  BOOST_TEST(false);
-}
-
-BOOST_TEST_DECORATOR(
-  + utf::depends_on("test_case2")
-)
-BOOST_AUTO_TEST_CASE( test_case5 )
-{
-  BOOST_TEST(false);
+  BOOST_TEST(1 == 1);
 }
 //]

doc/examples/example70_decorators.output

@@ -1,12 +1,12 @@
 //[example_output
-> example
-Running 3 test cases...
-test.cpp(24): error: in "test_case3": check false has failed
+> example70 --run_test=@trivial
+Running 2 test cases...
 
-*** 1 failure detected in test module "example"
+*** No errors detected
 
-> example --list_content
-test_case1
-test_case3
-test_case4
+
+> example70 --run_test=@cmp
+Running 1 test case...
+
+*** No errors detected
 //]

doc/examples/example71_decorators.cpp

@@ -6,29 +6,23 @@
 //  See http://www.boost.org/libs/test for the library home page.
 
 //[example_code
-#define BOOST_TEST_MODULE example
+#define BOOST_TEST_MODULE example71
 #include <boost/test/unit_test.hpp>
-
 namespace utf = boost::unit_test;
 
 BOOST_TEST_DECORATOR(
-  + utf::expected_failures(2)
+  + utf::label("trivial")
 )
 BOOST_AUTO_TEST_SUITE( suite1 )
 
-  BOOST_TEST_DECORATOR(
-    + utf::expected_failures(1)
-  )
   BOOST_AUTO_TEST_CASE( test_case1 )
   {
-    BOOST_TEST(false);
-    BOOST_TEST(false);
+    BOOST_TEST(true);
   }
-  
+
   BOOST_AUTO_TEST_CASE( test_case2 )
   {
-    BOOST_TEST(false);
-    BOOST_TEST(false);
+    BOOST_TEST(1 == 1);
   }
 
 BOOST_AUTO_TEST_SUITE_END()

doc/examples/example71_decorators.output

@@ -1,25 +1,6 @@
 //[example_output
-> example --report_level=detailed
+> example71 --run_test=@trivial
 Running 2 test cases...
-test.cpp(16): error: in "test_case1": check false has failed
-test.cpp(17): error: in "test_case1": check false has failed
-test.cpp(22): error: in "test_case2": check false has failed
-test.cpp(23): error: in "test_case2": check false has failed
 
-Test module "example" failed with:
-  2 test cases out of 2 failed
-  4 assertions out of 4 failed
-  3 expected failures
-
-  Test suite "suite1" failed with:
-    2 test cases out of 2 failed
-    4 assertions out of 4 failed
-    3 expected failures
-
-    Test case "test_case1" failed with:
-      2 assertions out of 2 failed
-      1 expected failure
-
-    Test case "test_case2" failed with:
-      2 assertions out of 2 failed
+*** No errors detected
 //]

doc/examples/example72_decorators.cpp

@@ -6,17 +6,28 @@
 //  See http://www.boost.org/libs/test for the library home page.
 
 //[example_code
-#define BOOST_TEST_MODULE example
+#define BOOST_TEST_MODULE example72
 #include <boost/test/unit_test.hpp>
-
 namespace utf = boost::unit_test;
 
+BOOST_AUTO_TEST_SUITE( suite1 )
+
+  BOOST_AUTO_TEST_CASE( test_case1 )
+  {
+    BOOST_TEST(true);
+  }
+
+BOOST_AUTO_TEST_SUITE_END()
+
 BOOST_TEST_DECORATOR(
-  + utf::timeout(2)
+  + utf::label("trivial")
 )
-BOOST_AUTO_TEST_CASE( test_case1 )
-{
-  for(;;) {}
-  BOOST_TEST(true);
-}
+BOOST_AUTO_TEST_SUITE( suite1 )
+
+  BOOST_AUTO_TEST_CASE( test_case2 )
+  {
+    BOOST_TEST(1 == 1);
+  }
+
+BOOST_AUTO_TEST_SUITE_END()
 //]

doc/examples/example72_decorators.output

@@ -1,8 +1,6 @@
 //[example_output
-> example
-Running 1 test case...
-unknown location(0): fatal error: in "test_case1": signal: SIGALRM (timeout while executing function)
-test.cpp(9): last checkpoint: "test_case1" entry.
+> example72 --run_test=@trivial
+Running 2 test cases...
 
-*** 1 failure detected in test module "example"
+*** No errors detected
 //]

doc/examples/example73_decorators.cpp

@@ -6,40 +6,30 @@
 //  See http://www.boost.org/libs/test for the library home page.
 
 //[example_code
-#include <iostream>
-#define BOOST_TEST_MODULE example
+#define BOOST_TEST_MODULE example73
 #include <boost/test/unit_test.hpp>
-
 namespace utf = boost::unit_test;
 
-struct Fx
-{
-  std::string s;
-  Fx(std::string s = "") : s(s)
-        { std::cout << "set up " << s << std::endl; }
-  ~Fx() { std::cout << "tear down " << s << std::endl; }
-};
-
-void setup() { std::cout << "set up fun" << std::endl; }
-void teardown() { std::cout << "tear down fun" << std::endl; }
-
 BOOST_TEST_DECORATOR(
-  + utf::fixture<Fx>(std::string("FX"))
-  + utf::fixture<Fx>(std::string("FX2"))
+  + utf::label("trivial")
 )
 BOOST_AUTO_TEST_SUITE( suite1 )
 
-  BOOST_TEST_DECORATOR(
-    + utf::fixture(&setup, &teardown)
-  )
   BOOST_AUTO_TEST_CASE( test_case1 )
   {
-    BOOST_TEST(false);
+    BOOST_TEST(true);
   }
-  
+
+BOOST_AUTO_TEST_SUITE_END()
+
+BOOST_TEST_DECORATOR(
+  + utf::label("simple")
+)
+BOOST_AUTO_TEST_SUITE( suite1 )
+
   BOOST_AUTO_TEST_CASE( test_case2 )
   {
-    BOOST_TEST(false);
+    BOOST_TEST(1 == 1);
   }
 
 BOOST_AUTO_TEST_SUITE_END()

doc/examples/example73_decorators.output

@@ -1,14 +1,10 @@
 //[example_output
-> example
-Running 2 test cases...
-set up FX
-set up FX2
-set up fun
-test.cpp(28): error: in "test_case1": check false has failed
-tear down fun
-test.cpp(33): error: in "test_case2": check false has failed
-tear down FX2
-tear down FX
+> example73 --run_test=@trivial
+Test setup error: no test cases matching filter
 
-*** 2 failures detected in test module "example"
+
+> example73 --run_test=@simple
+Running 2 test cases...
+
+*** No errors detected
 //]

doc/examples/example74_decorators.cpp

@@ -6,7 +6,7 @@
 //  See http://www.boost.org/libs/test for the library home page.
 
 //[example_code
-#define BOOST_TEST_MODULE example
+#define BOOST_TEST_MODULE example74
 #include <boost/test/unit_test.hpp>
 
 namespace utf = boost::unit_test;

doc/examples/example74_decorators.output

@@ -1,24 +1,24 @@
 //[example_output
-> example
+> example74
 Running 3 test cases...
 test.cpp(11): error: in "test_case1": check false has failed
 test.cpp(20): error: in "test_case2": check false has failed
 test.cpp(25): error: in "test_case3": check false has failed
 
-*** 3 failures detected in test module "example"
+*** 3 failures detected in test module "example74"
 
 
-> example --run_test=@l1
+> example74 --run_test=@l1
 Running 2 test cases...
 test.cpp(11): error: in "test_case1": check false has failed
 test.cpp(20): error: in "test_case2": check false has failed
 
-*** 2 failures detected in test module "example"
+*** 2 failures detected in test module "example74"
 
 
-> example --run_test=@l2
+> example74 --run_test=@l2
 Running 1 test case...
 test.cpp(20): error: in "test_case2": check false has failed
 
-*** 1 failure detected in test module "example"
+*** 1 failure detected in test module "example74"
 //]

doc/examples/example75_decorators.cpp

@@ -6,7 +6,7 @@
 //  See http://www.boost.org/libs/test for the library home page.
 
 //[example_code
-#define BOOST_TEST_MODULE example
+#define BOOST_TEST_MODULE example75
 #include <boost/test/unit_test.hpp>
 
 namespace utf = boost::unit_test;

doc/examples/example75_decorators.output

@@ -1,7 +1,7 @@
 //[example_output
-> example
+> example75
 Running 1 test case...
 test.cpp(12): error: in "test_case1": check false has failed
 
-*** 1 failure detected in test module "example"
+*** 1 failure detected in test module "example75"
 //]

doc/examples/example76_decorators.cpp

@@ -6,25 +6,45 @@
 //  See http://www.boost.org/libs/test for the library home page.
 
 //[example_code
-#define BOOST_TEST_MODULE example
+#define BOOST_TEST_MODULE example76
 #include <boost/test/unit_test.hpp>
+
 namespace utf = boost::unit_test;
 
-BOOST_TEST_DECORATOR(
-  + utf::label("trivial")
-)
 BOOST_AUTO_TEST_CASE( test_case1 )
 {
   BOOST_TEST(true);
 }
 
 BOOST_TEST_DECORATOR(
-  + utf::label("trivial")
-  + utf::label("cmp")
-  + utf::description("testing equality of ones")
+  + utf::enable_if(false)
 )
 BOOST_AUTO_TEST_CASE( test_case2 )
 {
-  BOOST_TEST(1 == 1);
+  BOOST_TEST(false);
+}
+
+BOOST_TEST_DECORATOR(
+  + utf::depends_on("test_case1")
+)
+BOOST_AUTO_TEST_CASE( test_case3 )
+{
+  BOOST_TEST(false);
+}
+
+BOOST_TEST_DECORATOR(
+  + utf::depends_on("test_case3")
+)
+BOOST_AUTO_TEST_CASE( test_case4 )
+{
+  BOOST_TEST(false);
+}
+
+BOOST_TEST_DECORATOR(
+  + utf::depends_on("test_case2")
+)
+BOOST_AUTO_TEST_CASE( test_case5 )
+{
+  BOOST_TEST(false);
 }
 //]

doc/examples/example76_decorators.output

@@ -1,12 +1,12 @@
 //[example_output
-> example --run_test=@trivial
-Running 2 test cases...
+> example76
+Running 3 test cases...
+test.cpp(24): error: in "test_case3": check false has failed
 
-*** No errors detected
+*** 1 failure detected in test module "example76"
 
-
-> example --run_test=@cmp
-Running 1 test case...
-
-*** No errors detected
+> example76 --list_content
+test_case1
+test_case3
+test_case4
 //]

doc/examples/example77_decorators.cpp

@@ -6,23 +6,29 @@
 //  See http://www.boost.org/libs/test for the library home page.
 
 //[example_code
-#define BOOST_TEST_MODULE example
+#define BOOST_TEST_MODULE example77
 #include <boost/test/unit_test.hpp>
+
 namespace utf = boost::unit_test;
 
 BOOST_TEST_DECORATOR(
-  + utf::label("trivial")
+  + utf::expected_failures(2)
 )
 BOOST_AUTO_TEST_SUITE( suite1 )
 
+  BOOST_TEST_DECORATOR(
+    + utf::expected_failures(1)
+  )
   BOOST_AUTO_TEST_CASE( test_case1 )
   {
-    BOOST_TEST(true);
+    BOOST_TEST(false);
+    BOOST_TEST(false);
   }
-
+  
   BOOST_AUTO_TEST_CASE( test_case2 )
   {
-    BOOST_TEST(1 == 1);
+    BOOST_TEST(false);
+    BOOST_TEST(false);
   }
 
 BOOST_AUTO_TEST_SUITE_END()

doc/examples/example77_decorators.output

@@ -1,6 +1,25 @@
 //[example_output
-> example --run_test=@trivial
+> example77 --report_level=detailed
 Running 2 test cases...
+test.cpp(16): error: in "test_case1": check false has failed
+test.cpp(17): error: in "test_case1": check false has failed
+test.cpp(22): error: in "test_case2": check false has failed
+test.cpp(23): error: in "test_case2": check false has failed
 
-*** No errors detected
+Test module "example77" failed with:
+  2 test cases out of 2 failed
+  4 assertions out of 4 failed
+  3 expected failures
+
+  Test suite "suite1" failed with:
+    2 test cases out of 2 failed
+    4 assertions out of 4 failed
+    3 expected failures
+
+    Test case "test_case1" failed with:
+      2 assertions out of 2 failed
+      1 expected failure
+
+    Test case "test_case2" failed with:
+      2 assertions out of 2 failed
 //]

doc/examples/example78_decorators.cpp

@@ -6,28 +6,17 @@
 //  See http://www.boost.org/libs/test for the library home page.
 
 //[example_code
-#define BOOST_TEST_MODULE example
+#define BOOST_TEST_MODULE example78
 #include <boost/test/unit_test.hpp>
+
 namespace utf = boost::unit_test;
 
-BOOST_AUTO_TEST_SUITE( suite1 )
-
-  BOOST_AUTO_TEST_CASE( test_case1 )
-  {
-    BOOST_TEST(true);
-  }
-
-BOOST_AUTO_TEST_SUITE_END()
-
 BOOST_TEST_DECORATOR(
-  + utf::label("trivial")
+  + utf::timeout(2)
 )
-BOOST_AUTO_TEST_SUITE( suite1 )
-
-  BOOST_AUTO_TEST_CASE( test_case2 )
-  {
-    BOOST_TEST(1 == 1);
-  }
-
-BOOST_AUTO_TEST_SUITE_END()
+BOOST_AUTO_TEST_CASE( test_case1 )
+{
+  for(;;) {}
+  BOOST_TEST(true);
+}
 //]

doc/examples/example78_decorators.output

@@ -1,6 +1,8 @@
 //[example_output
-> example --run_test=@trivial
-Running 2 test cases...
+> example78
+Running 1 test case...
+unknown location(0): fatal error: in "test_case1": signal: SIGALRM (timeout while executing function)
+test.cpp(9): last checkpoint: "test_case1" entry.
 
-*** No errors detected
+*** 1 failure detected in test module "example78"
 //]

doc/examples/example79_decorators.cpp

@@ -6,30 +6,40 @@
 //  See http://www.boost.org/libs/test for the library home page.
 
 //[example_code
-#define BOOST_TEST_MODULE example
+#include <iostream>
+#define BOOST_TEST_MODULE example79
 #include <boost/test/unit_test.hpp>
+
 namespace utf = boost::unit_test;
 
+struct Fx
+{
+  std::string s;
+  Fx(std::string s = "") : s(s)
+        { std::cout << "set up " << s << std::endl; }
+  ~Fx() { std::cout << "tear down " << s << std::endl; }
+};
+
+void setup() { std::cout << "set up fun" << std::endl; }
+void teardown() { std::cout << "tear down fun" << std::endl; }
+
 BOOST_TEST_DECORATOR(
-  + utf::label("trivial")
+  + utf::fixture<Fx>(std::string("FX"))
+  + utf::fixture<Fx>(std::string("FX2"))
 )
 BOOST_AUTO_TEST_SUITE( suite1 )
 
+  BOOST_TEST_DECORATOR(
+    + utf::fixture(&setup, &teardown)
+  )
   BOOST_AUTO_TEST_CASE( test_case1 )
   {
-    BOOST_TEST(true);
+    BOOST_TEST(false);
   }
-
-BOOST_AUTO_TEST_SUITE_END()
-
-BOOST_TEST_DECORATOR(
-  + utf::label("simple")
-)
-BOOST_AUTO_TEST_SUITE( suite1 )
-
+  
   BOOST_AUTO_TEST_CASE( test_case2 )
   {
-    BOOST_TEST(1 == 1);
+    BOOST_TEST(false);
   }
 
 BOOST_AUTO_TEST_SUITE_END()

doc/examples/example79_decorators.output

@@ -1,10 +1,14 @@
 //[example_output
-> example --run_test=@trivial
-Test setup error: no test cases matching filter
-
-
-> example --run_test=@simple
+> example79
 Running 2 test cases...
+set up FX
+set up FX2
+set up fun
+test.cpp(28): error: in "test_case1": check false has failed
+tear down fun
+test.cpp(33): error: in "test_case2": check false has failed
+tear down FX2
+tear down FX
 
-*** No errors detected
+*** 2 failures detected in test module "example79"
 //]

doc/test.qbk

@@ -175,8 +175,8 @@
 
 [section:example_ref[name] [descr]] 
 
-[import examples/example[name].cpp]
-[import examples/example[name].output]
+[import examples/[name].cpp]
+[import examples/[name].output]
 
 [heading Source]
 [example_code]

doc/test_organization/decorators.qbk

@@ -9,7 +9,7 @@
 
 Decorators provide a way to configure certain aspects of a test unit.
 
-[bt_example example76_decorators..Test unit decorators]
+[bt_example example70_decorators..Test unit decorators]
 
 Test case `test_case1` has one associated ['decorator:] `label`. This means that when test units are executed selectively by label, this test case will match to label "trivial". Test case `test_case2` has three associated decorators: two of type `label` and one of type `description`. 
 
@@ -19,19 +19,19 @@ Test case `test_case1` has one associated ['decorator:] `label`. This means that
 
 It is also possible to decorate test suites. 
 
-[bt_example example77_decorators..Test suite decorators]
+[bt_example example71_decorators..Test suite decorators]
 
 The meaning of such decoration is that it applies to every test unit inside the suite. In the case above both test cases `suite1/test_case1` and `suite1/test_case2` have tag "trivial".
 
 A decorator applies to every test unit in the suite, even if the scope of a given suite is opened twice:
 
-[bt_example example78_decorators..Decorators on multiple suite openings]
+[bt_example example72_decorators..Decorators on multiple suite openings]
 
 In the above case, both test cases `suite1.test_case1` and `suite1/test_case2` have tag "trivial".
 
 In case the scope of the suite is opened twice in the same file with different decorator sets, the last decorator set is in effect:
 
-[bt_example example79_decorators..Different decorators on multiple suite openings]
+[bt_example example73_decorators..Different decorators on multiple suite openings]
 
 In the above case, both test cases `suite1/test_case1` and `suite1/test_case2` have tag "simple". Tag "trivial" has been overwritten.
 
@@ -74,7 +74,7 @@ depeneds_on(const_string dependent_test_name);
 
 Decorator `depends_on` disables the test unit from being run if the test unit marked as its dependency, is either disabled or is executed and marked as failed. 
 
-[bt_example example70_decorators..Decorator depends_on]
+[bt_example example76_decorators..Decorator depends_on]
 
 In the above scenario, `test_case2` is not even listed because it is disabled; `test_case5` is not listed because it depends on a disabled test unit. `test_case4` is listed but not executed because it depends on `test_case3`, which failed.
 
@@ -87,7 +87,7 @@ expected_failures(counter_t number);
 
 Decorator `expected_failures` defines the number of expected failures that will be reported upon program execution. At suite level this defines the number of expected failures per suite. The total number of expected failures per suite is the sum of per-suite decorator and per-test decorators inside the suite:
 
-[bt_example example71_decorators..Decorator expected_failures]
+[bt_example example77_decorators..Decorator expected_failures]
 
 
 [h3 timeout]
@@ -98,10 +98,13 @@ timeout(unsigned seconds);
 
 Decorator `timeout` specifies time (in seconds) that sets the maximum allowed duration of a test case. If this time is exceeded the test unit is forced to stop and is reported as failure.
 
-[bt_example example72_decorators..Decorator timeout]
+[bt_example example78_decorators..Decorator timeout]
+
+Applied at test suite level, this decorator has no effect.
 
 [caution Decorator `timeout` has no effect on Windows build. This feature is not implemented on Windows yet.]
 
+
 [h3 fixture]
 
 ``
@@ -116,7 +119,7 @@ template <typename Fx, typename Arg>
 
 Decorator `fixture` specifies a pair of functions (like `set_up` and `tear_down`) to be called before and after the corresponding test unit. At the suite level the `set_up` function is called once -- before the suite execution starts and `tear_down` function is called once -- after the suite execution ends. It comes in three forms. First expects two functions for set-up and tear-down (the second one can be skipped). The second expects a `DefaultConstructible` class. Its default constructor will be used as set-up function and its destructor as a tear-down function. Third requires a class with one-argument public constructor. Argument `arg` is forwarded to the constructor and this is the set-up function, its destructor is the tear-down function. There is no way to get access to the members of these fixtures from within the test case or test suite.
 
-[bt_example example73_decorators..Decorator fixture]
+[bt_example example79_decorators..Decorator fixture]
 
 [endsect] [/ section available_decorators]