From 2ae4985d2649c581d2da666263b02b76152cb8a6 Mon Sep 17 00:00:00 2001
From: Jack Grigg <jack@z.cash>
Date: Thu, 6 Aug 2020 11:37:27 +0100
Subject: [PATCH] tracing: Document macro arguments that MUST be static
 constant UTF-8 strings

---
 src/rust/include/tracing.h | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/src/rust/include/tracing.h b/src/rust/include/tracing.h
index 95bdd89e8..89bd87c4a 100644
--- a/src/rust/include/tracing.h
+++ b/src/rust/include/tracing.h
@@ -46,7 +46,8 @@ typedef struct TracingCallsite TracingCallsite;
 /// macros such as `TracingInfo`) instead of calling this directly.
 ///
 /// This MUST ONLY be called to assign a `static TracingCallsite*`, and all
-/// string arguments MUST be static `const char*` constants.
+/// string arguments MUST be static `const char*` constants, and MUST be valid
+/// UTF-8.
 TracingCallsite* tracing_callsite(
     const char* name,
     const char* target,
@@ -237,6 +238,9 @@ class Span
 /// The `Span::Enter` method on that object records that the span has been
 /// entered, and returns a RAII guard object, which will exit the span when
 /// dropped.
+///
+/// level, target, and name MUST be static constants, and MUST be valid UTF-8
+/// strings.
 #define TracingSpan(level, target, name) ([&] {        \
     static constexpr const char* const FIELDS[] = {};  \
     static TracingCallsite* CALLSITE =                 \
@@ -250,6 +254,8 @@ class Span
 //
 
 /// Constructs a new event.
+///
+/// level and target MUST be static constants, and MUST be valid UTF-8 strings.
 #define TracingLog(level, target, message)                   \
     do {                                                     \
         static constexpr const char* const FIELDS[] =        \
@@ -262,14 +268,34 @@ class Span
     } while (0)
 
 /// Constructs an event at the error level.
+///
+/// Arguments: (target, message)
+///
+/// target MUST be a static constant, and MUST be valid UTF-8 string.
 #define TracingError(...) TracingLog("error", __VA_ARGS__)
 /// Constructs an event at the warn level.
+///
+/// Arguments: (target, message)
+///
+/// target MUST be a static constant, and MUST be valid UTF-8 string.
 #define TracingWarn(...) TracingLog("warn", __VA_ARGS__)
 /// Constructs an event at the info level.
+///
+/// Arguments: (target, message)
+///
+/// target MUST be a static constant, and MUST be valid UTF-8 string.
 #define TracingInfo(...) TracingLog("info", __VA_ARGS__)
 /// Constructs an event at the debug level.
+///
+/// Arguments: (target, message)
+///
+/// target MUST be a static constant, and MUST be valid UTF-8 string.
 #define TracingDebug(...) TracingLog("debug", __VA_ARGS__)
 /// Constructs an event at the trace level.
+///
+/// Arguments: (target, message)
+///
+/// target MUST be a static constant, and MUST be valid UTF-8 string.
 #define TracingTrace(...) TracingLog("trace", __VA_ARGS__)
 
 #endif // TRACING_INCLUDE_H_