extern int bees_trace_level;
/// Register a RAII trace entry that fires if the enclosing scope exits
-/// unexpectedly (exception or early return). @p x is a stream expression.
+/// unexpectedly (exception or early return). The rendered trace line
+/// automatically includes the enclosing function name (@c __FUNCTION__)
+/// as a prefix and @c __FILE__:__LINE__ as a suffix; @p x supplies only
+/// the call-site-specific payload between them. Example:
+/// @code
+/// BEESTRACE("ref " << ref); // -> "MyClass::foo: ref <ref> at bees-foo.cc:42"
+/// @endcode
+/// @warning Do not write @c BEESTRACE(__FUNCTION__ << ": " << ...) — the
+/// function name is already injected and the result will be doubled.
+/// Unlike BEESLOG and BEESNOTE, which do @e not prefix the function
+/// name, BEESTRACE handles that for you.
#define BEESTRACE(x) \
BeesTracer SRSLY_WTF_C(beesTracer_, __LINE__) { [&, __func = __FUNCTION__](ostream &_os) { _os << __func << ": " << x << " at " << __FILE__ << ":" << __LINE__; } }