]> git.hungrycats.org Git - bees/commitdiff
trace: document BEESTRACE auto-prefix in the doxygen comment
authorZygo Blaxell <bees@furryterror.org>
Sat, 30 May 2026 17:37:04 +0000 (13:37 -0400)
committerZygo Blaxell <bees@furryterror.org>
Tue, 6 Oct 2026 05:51:40 +0000 (01:51 -0400)
The BEESTRACE macro already injects __FUNCTION__ as a prefix and
__FILE__:__LINE__ as a suffix on the rendered trace line, but the
existing doxygen comment described only the RAII semantics.  Callers
unfamiliar with the macro's expansion would routinely add a redundant
"__FUNCTION__ << \": \"" to the body (carried over from BEESLOG* and
BEESNOTE, neither of which prefixes the function name) and produce
doubled output like "foo: foo: ref ...".

Expand the comment to:

  - state explicitly that __FUNCTION__ and __FILE__:__LINE__ are
    injected automatically, so the argument supplies only the
    call-site payload;
  - show an @code example demonstrating the right form and its
    rendered output;
  - add an @warning admonition that explicitly rejects
    `BEESTRACE(__FUNCTION__ << ": " << ...)` and contrasts the macro
    with BEESLOG / BEESNOTE.

Comment-only change; no behavior or generated code is affected.

Assisted-by: Claude-Code:claude-opus-4-7
Signed-off-by: Zygo Blaxell <bees@furryterror.org>
src/bees.h

index 64b667d079edee0e6548d3d88d081822cd23b4c8..b0afb55801fac393d93d4987a1ae96d94d2df56b 100644 (file)
@@ -186,7 +186,17 @@ const int FLAGS_CREATE_FILE   = FLAGS_OPEN_COMMON | O_RDWR   | O_CREAT | O_EXCL;
 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__; } }