Adjust flags documentation ordering

opentelemetry/proto/trace/v1/trace.proto

@@ -113,20 +113,17 @@ message Span {
   // flags as defined in W3C Trace Context specification.
   // To read the 8-bit W3C trace flag, use `flags & SPAN_FLAGS_TRACE_FLAGS_MASK`.
   //
-  // When creating span messages, if the message is logically forwarded from another source
-  // with an equivalent flags fields (i.e., usually another OTLP span message), the field SHOULD
-  // be copied as-is. If creating from a source that does not have an equivalent flags field
-  // (such as a runtime representation of an OpenTelemetry span), the high 22 bits MUST
-  // be set to zero.
-  //
-  // [Optional].
-  //
   // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions.
   //
   // Bits 8 and 9 represent the 3 states of whether a span's parent
   // is remote. The states are unknown, is not remote, is remote.
   // To read the 2-bit flag, use `flags & SPAN_FLAGS_PARENT_OR_LINK_IS_REMOTE_MASK`.
   //
+  // When creating span messages, if the message is logically forwarded from another source
+  // with an equivalent flags fields (i.e., usually another OTLP span message), the field SHOULD
+  // be copied as-is. If creating from a source that does not have an equivalent flags field
+  // (such as a runtime representation of an OpenTelemetry span), the high 22 bits MUST
+  // be set to zero.
   // Readers MUST NOT assume that bits 10-31 (22 most significant bits) will be zero.
   //
   // [Optional].
@@ -266,18 +263,20 @@ message Span {
     // then no attributes were dropped.
     uint32 dropped_attributes_count = 5;
 
-    // Flags, a bit field. Bit 0-7 (8 least significant bits) are the trace
-    // flags as defined in W3C Trace Context specification. Readers
-    // MUST not assume that bits 10-31 (22 most significant bits) will be zero.
-    // When creating new spans, bits 10-31 (most-significant 22-bits) MUST be
-    // zero. To read the 8-bit W3C trace flag (use flags &
-    // SPAN_FLAGS_TRACE_FLAGS_MASK).  [Optional].
+    // Flags, a bit field. Bits 0-7 (8 least significant bits) are the trace
+    // flags as defined in W3C Trace Context specification. To read the 8-bit W3C trace
+    // flag, use `flags & SPAN_FLAGS_TRACE_FLAGS_MASK`.
     //
     // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions.
     //
-    // Bits 8 and 9 represent the 3 states of whether the link
-    // is remote. The states are unknown, is not remote, is remote.
+    // Bits 8 and 9 represent the 3 states of whether the link is remote. The states
+    // are unknown, is not remote, is remote.
     // To read the 2-bit flag, use `flags & SPAN_FLAGS_PARENT_OR_LINK_IS_REMOTE_MASK`.
+    //
+    // Readers MUST NOT assume that bits 10-31 (22 most significant bits) will be zero.
+    // When creating new spans, bits 10-31 (most-significant 22-bits) MUST be zero.
+    //
+    // [Optional].
     fixed32 flags = 6;
   }
 
@@ -340,7 +339,7 @@ enum SpanFlags {
   // Bits 0-7 are used for trace flags.
   SPAN_FLAGS_TRACE_FLAGS_MASK = 0x000000FF;
 
-  // Bits 8 and 9 are used for the parent or link is remote flag.
+  // Bits 8 and 9 are used to indicate that the parent span or link span is remote.
   // See SpanFlagsParentIsRemote and SpanFlagsLinkIsRemote for the
   // valid values.
   SPAN_FLAGS_PARENT_OR_LINK_IS_REMOTE_MASK = 0x00000300;