From 1701325caa11af8ceff92c7254e12f5a8f77ada5 Mon Sep 17 00:00:00 2001
From: Omer Ozarslan <omer@utdallas.edu>
Date: Sun, 3 Feb 2019 19:41:41 -0600
Subject: [PATCH] Document unscoped info

---
 docs/logging.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 60 insertions(+), 2 deletions(-)

diff --git a/docs/logging.md b/docs/logging.md
index f6ad81a3..e896a570 100644
--- a/docs/logging.md
+++ b/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,60 @@ 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 an unscoped message is not tied to its own scope.
+- An unscoped message can be reported by the first following assertion only, regardless of the result of that assertion.
+
+In other words, lifetime of `UNSCOPED_INFO` is limited by the following assertion (or by the end of test case/section, whichever comes first) whereas lifetime of `INFO` is limited by its own scope.
+
+These differences make this macro useful for reporting information from helper functions or inner scopes. 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 +97,15 @@ 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 not limited to their own scope: They are removed from the buffer after each assertion, section or test case, whichever comes first.
+
 **WARN(** _message expression_ **)**
 
 The message is always reported but does not fail the test.