From 2aeea61964d8aa32e884eee4cbea4576f5410fa5 Mon Sep 17 00:00:00 2001
From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>
Date: Fri, 17 Jul 2026 22:11:24 +0100
Subject: [PATCH] docs(telemetry): use SpanNames constants (not literals) in
 SpanGuard @code examples

The otel-naming Rule F check scans @code doc examples as call sites; raw
string literals there trip the rule. Reference *SpanNames.h constants /
placeholder identifiers in the examples so comments follow the naming rules.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 include/xrpl/telemetry/SpanGuard.h | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/include/xrpl/telemetry/SpanGuard.h b/include/xrpl/telemetry/SpanGuard.h
index 622e1d667f..ea8d0f9569 100644
--- a/include/xrpl/telemetry/SpanGuard.h
+++ b/include/xrpl/telemetry/SpanGuard.h
@@ -57,8 +57,8 @@
  *     using namespace xrpl::telemetry;
  *
  *     auto span = SpanGuard::span(
- *         TraceCategory::Rpc, rpc_span::prefix::command, "submit");
- *     span.setAttribute(rpc_span::attr::command, "submit");
+ *         TraceCategory::Rpc, rpc_span::prefix::command, commandName);
+ *     span.setAttribute(rpc_span::attr::command, commandName);
  *     span.setAttribute(rpc_span::attr::rpcStatus, rpc_span::val::success);
  *     // span ended automatically on scope exit
  * @endcode
@@ -66,7 +66,7 @@
  * 2. Error recording:
  * @code
  *     auto span = SpanGuard::span(
- *         TraceCategory::Rpc, rpc_span::prefix::command, "submit");
+ *         TraceCategory::Rpc, rpc_span::prefix::command, commandName);
  *     try {
  *         doWork();
  *         span.setOk();
@@ -112,20 +112,27 @@
  *
  * 6. Fresh trace root at an inbound entry point (primary rootSpan use):
  * @code
+ *     #include <xrpld/overlay/detail/PeerSpanNames.h>
+ *     using namespace xrpl::telemetry;
+ *
  *     // A peer message handled on a shared worker thread that may
  *     // already have unrelated spans active — start a clean root so
- *     // those do not become parents of this trace.
+ *     // those do not become parents of this trace. Names come from a
+ *     // *SpanNames.h header, never raw literals.
  *     auto span = SpanGuard::rootSpan(
- *         TraceCategory::Peer, "peer", "validation.receive");
- *     span.setAttribute("ledger_hash", hashStr);
+ *         TraceCategory::Peer, seg::peer, peer_span::op::validationReceive);
+ *     span.setAttribute(peer_span::attr::ledgerHash, hashStr);
  * @endcode
  *
  * 7. Hand a span to a job on another thread (edge case, detached):
  * @code
+ *     #include <xrpld/app/ledger/detail/LedgerSpanNames.h>
+ *     using namespace xrpl::telemetry;
+ *
  *     // Build the guard on THIS thread, then strip its thread-local
  *     // Scope so it can be safely moved into a job and ended there.
  *     auto span = SpanGuard::span(
- *         TraceCategory::Ledger, "ledger", "build");
+ *         TraceCategory::Ledger, seg::ledger, ledger_span::op::build);
  *     jobQueue.addJob(
  *         [g = std::move(span).detached()]() mutable {
  *             doWork();