[llvm] [mlir] [MLIR] Add debug log to the pass manager (NFC) (PR #156205)

[Andrzej Warzyński via llvm-commits]

================
@@ -19,31 +19,41 @@
 namespace llvm {
 #ifndef NDEBUG
 
-// LDBG() is a macro that can be used as a raw_ostream for debugging.
-// It will stream the output to the dbgs() stream, with a prefix of the
-// debug type and the file and line number. A trailing newline is added to the
-// output automatically. If the streamed content contains a newline, the prefix
-// is added to each beginning of a new line. Nothing is printed if the debug
-// output is not enabled or the debug type does not match.
-//
-// E.g.,
-//   LDBG() << "Bitset contains: " << Bitset;
-// is somehow equivalent to
-//   LLVM_DEBUG(dbgs() << "[" << DEBUG_TYPE << "] " << __FILE__ << ":" <<
-//   __LINE__ << " "
-//              << "Bitset contains: " << Bitset << "\n");
-//
+/// LDBG() is a macro that can be used as a raw_ostream for debugging.
+/// It will stream the output to the dbgs() stream, with a prefix of the
+/// debug type and the file and line number. A trailing newline is added to the
+/// output automatically. If the streamed content contains a newline, the prefix
+/// is added to each beginning of a new line. Nothing is printed if the debug
+/// output is not enabled or the debug type does not match.
+///
+/// E.g.,
+///   LDBG() << "Bitset contains: " << Bitset;
+/// is somehow equivalent to
+///   LLVM_DEBUG(dbgs() << "[" << DEBUG_TYPE << "] " << __FILE__ << ":" <<
+///   __LINE__ << " "
+///              << "Bitset contains: " << Bitset << "\n");
+///
 // An optional `level` argument can be provided to control the verbosity of the
-// output. The default level is 1, and is in increasing level of verbosity.
-//
-// The `level` argument can be a literal integer, or a macro that evaluates to
-// an integer.
-//
-// An optional `type` argument can be provided to control the debug type. The
-// default type is DEBUG_TYPE. The `type` argument can be a literal string, or a
-// macro that evaluates to a string.
+/// output. The default level is 1, and is in increasing level of verbosity.
+///
+/// The `level` argument can be a literal integer, or a macro that evaluates to
+/// an integer.
+///
+/// An optional `type` argument can be provided to control the debug type. The
+/// default type is DEBUG_TYPE. The `type` argument can be a literal string, or
+/// a macro that evaluates to a string.
 #define LDBG(...) _GET_LDBG_MACRO(__VA_ARGS__)(__VA_ARGS__)
 
+/// LDBG_OS() is a macro that can be used as a raw_ostream for debugging.
+/// It will stream the output to the dbgs() stream, with a prefix of the
+/// debug type and the file and line number. A trailing newline is added to the
+/// output automatically. If the streamed content contains a newline, the prefix
+/// is added to each beginning of a new line. Nothing is printed if the debug
+/// output is not enabled or the debug type does not match.
+/// Note: this macro isn't guarded by a debug flag so it will always print in
+/// assert builds.
+#define LDBG_OS(...) _GET_LDBG_OS_MACRO(__VA_ARGS__)(__VA_ARGS__)
----------------
banach-space wrote:

Thanks Mehdi, the updated doc provides the clarification that I was missing - it's very helpful!

I still have this high-level concern re `LDBG_OS()` - it is very similar to `LDBG()` :) Ideally, we should re-use the existing code more, but it's not clear to me how to get there.

Some high-level observations:
1. Both `LDBG_OS()`and `LDBG()` return a `raw_stream`
2. `LDBG()` is "NULL" if `DEBUG_TYPE` doesn't match.
3. `LDBG_OS()` is non-"NULL" regardless of the debug type, but since you wrap it in `LLVM_DEBUG`, it is also _effectively_ "NULL" when `DEBUG_TYPE` does not match.
4. `LDBG_OS` sets `ShouldPrefixNextString` and `ShouldEmitNewLineOnDestruction`. `LLDB()` does not. 

To me it feels like 4. is the key differentiating factor. Is this correct? If yes, I would try to convey that in the doc for `LDBG_OS`.

https://github.com/llvm/llvm-project/pull/156205