trace: document BEESTRACE auto-prefix in the doxygen comment

trace: document BEESTRACE auto-prefix in the doxygen comment

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>