Document unscoped info

docs/logging.md

@@ -1,7 +1,7 @@
 <a id="top"></a>
 # Logging macros
 
-Additional messages can be logged during a test case. Note that the messages are scoped and thus will not be reported if failure occurs in scope preceding the message declaration. An example:
+Additional messages can be logged during a test case. Note that the messages logged with `INFO` are scoped and thus will not be reported if failure occurs in scope preceding the message declaration. An example:
 
 ```cpp
 TEST_CASE("Foo") {
@@ -28,6 +28,58 @@ The number is 1
 ```
 When the last `CHECK` fails in the "Bar" test case, then only one message will be printed: `Test case start`.
 
+## Logging without local scope
+
+`UNSCOPED_INFO` is similar to `INFO` with two key differences:
+
+- Lifetime of unscoped info is not tied to its own scope.
+- Unscoped info can be reported by the first following assertion only, regardless of the result of that assertion.
+
+This macro can be used for reporting information from helper functions or inner scopes because lifetime of `UNSCOPED_INFO` is limited by the assertion following whereas lifetime of `INFO` is limited by its own scope. An example:
+
+```cpp
+void print_some_info() {
+    UNSCOPED_INFO("Info from helper");
+}
+
+TEST_CASE("Baz") {
+    print_some_info();
+    for (int i = 0; i < 2; ++i) {
+        UNSCOPED_INFO("The number is " << i);
+    }
+    CHECK(false);
+}
+
+TEST_CASE( "Qux" ) {
+    INFO("First info");
+    UNSCOPED_INFO("First unscoped info");
+    CHECK(false);
+
+    INFO("Second info");
+    UNSCOPED_INFO("Second unscoped info");
+    CHECK(false);
+}
+```
+
+"Baz" test case prints:
+```
+Info from helper
+The number is 0
+The number is 1
+```
+
+With "Qux" test case, two messages will be printed when the first `CHECK` fails:
+```
+First info
+First unscoped info
+```
+
+"First unscoped info" message will be cleared after the first `CHECK`, while "First info" message will persist until the end of the test case. Therefore, when the second `CHECK` fails, three messages will be printed:
+```
+First info
+Second info
+Second unscoped info
+```
 
 ## Streaming macros
 
@@ -43,11 +95,17 @@ These macros come in three forms:
 
 **INFO(** _message expression_ **)**
 
-The message is logged to a buffer, but only reported with the next assertion that is logged. This allows you to log contextual information in case of failures which is not shown during a successful test run (for the console reporter, without -s). Messages are removed from the buffer at the end of their scope, so may be used, for example, in loops.
+The message is logged to a buffer, but only reported with next assertions that are logged. This allows you to log contextual information in case of failures which is not shown during a successful test run (for the console reporter, without -s). Messages are removed from the buffer at the end of their scope, so may be used, for example, in loops.
 
 _Note that in Catch2 2.x.x `INFO` can be used without a trailing semicolon as there is a trailing semicolon inside macro.
 This semicolon will be removed with next major version. It is highly advised to use a trailing semicolon after `INFO` macro._
 
+**UNSCOPED_INFO(** _message expression_ **)**
+
+Similar to `INFO`, but messages are removed from the buffer after each assertion and they are not limited to their own scopes.
+
+_Note: Unscoped messages are cleared after `WARN` as well._
+
 **WARN(** _message expression_ **)**
 
 The message is always reported but does not fail the test.