add comment, and reorganize

api/include/opentelemetry/trace/context.h

@@ -23,6 +23,16 @@ inline nostd::shared_ptr<Span> GetSpan(const context::Context &context) noexcept
   return nostd::shared_ptr<Span>(new DefaultSpan(SpanContext::GetInvalid()));
 }
 
+inline bool IsRootSpan(const context::Context &context) noexcept
+{
+  context::ContextValue is_root_span = context.GetValue(kIsRootSpanKey);
+  if (nostd::holds_alternative<bool>(is_root_span))
+  {
+    return nostd::get<bool>(is_root_span);
+  }
+  return false;
+}
+
 // Set Span into explicit context
 inline context::Context SetSpan(context::Context &context, nostd::shared_ptr<Span> span) noexcept
 {

api/include/opentelemetry/trace/span_metadata.h

@@ -21,6 +21,7 @@ enum class SpanKind
 
 // The key identifies the active span in the current context.
 constexpr char kSpanKey[] = "active_span";
+constexpr char kIsRootSpanKey[] = "is_root_span";
 
 // StatusCode - Represents the canonical set of status codes of a finished Span.
 enum class StatusCode

api/include/opentelemetry/trace/span_startoptions.h

@@ -34,8 +34,23 @@ struct StartSpanOptions
 
   // Explicitly set the parent of a Span.
   //
-  // This defaults to an invalid span context. In this case, the Span is
-  // automatically parented to the currently active span.
+  // The `parent` field in `StartSpanOptions` struct is designed to establish
+  // parent-child relationships in tracing spans. It can be set to either a 
+  // `SpanContext` or a `context::Context` object.
+  //
+  // - When set to valid `SpanContext`, it directly assigns a specific Span as the parent 
+  // of the newly created Span.
+  //
+  // - Alternatively, setting the `parent` field to a `context::Context` allows for 
+  // more nuanced parent identification:
+  //   1. If the `Context` contains a Span object, this Span is treated as the parent.
+  //   2. If the `Context` contains the boolean flag `is_root_span` set to `true`,
+  //      it indicates that the new Span should be treated as a root Span, i.e., it 
+  //      does not have a parent Span.
+  // 
+  // - If the `parent` field is not set, the newly created Span will inherit the
+  // parent of the currently active Span (if any) in the current context.
+  //
   nostd::variant<SpanContext, context::Context> parent = SpanContext::GetInvalid();
 
   // TODO:

sdk/src/trace/tracer.cc

@@ -45,14 +45,9 @@ nostd::shared_ptr<opentelemetry::trace::Span> Tracer::StartSpan(
     }
     else
     {
-      context::ContextValue is_root_span = context.GetValue("is_root_span");
-      if (nostd::holds_alternative<bool>(is_root_span))
-      {
-        if (nostd::get<bool>(is_root_span))
-        {
+      if (opentelemetry::trace::IsRootSpan(context)) {
           parent_context = opentelemetry::trace::SpanContext{false, false};
         }
-      }
     }
   }