Clarify that zero values bitfield helper enums should not be used

opentelemetry/proto/logs/v1/logs.proto

@@ -104,10 +104,21 @@ enum SeverityNumber {
   SEVERITY_NUMBER_FATAL4 = 24;
 }
 
-// Masks for LogRecord.flags field.
+// LogRecordFlags is defined as a protobuf 'uint32' type and is to be used as
+// bit-fields. Each non-zero value defined in this enum is a bit-mask.
+// To extract the bit-field, for example, use an expression like:
+//
+//   (logRecord.flags & LOG_RECORD_FLAG_TRACE_FLAGS_MASK)
+//
 enum LogRecordFlags {
-  LOG_RECORD_FLAG_UNSPECIFIED = 0;
+  // The zero value for the enum. Should not be used for comparisons.
+  // Instead use bitwise "and" with the appropriate mask as shown above.
+  LOG_RECORD_FLAG_DO_NOT_USE = 0;
+
+  // Bits 0-7 are used for trace flags.
   LOG_RECORD_FLAG_TRACE_FLAGS_MASK = 0x000000FF;
+
+  // Bits 8-31 are reserved for future use.
 }
 
 // A log record according to OpenTelemetry Log Data Model:

opentelemetry/proto/metrics/v1/metrics.proto

@@ -316,15 +316,17 @@ enum AggregationTemporality {
 // enum is a bit-mask.  To test the presence of a single flag in the flags of
 // a data point, for example, use an expression like:
 //
-//   (point.flags & FLAG_NO_RECORDED_VALUE) == FLAG_NO_RECORDED_VALUE
+//   (point.flags & FLAG_NO_RECORDED_VALUE_MASK) == FLAG_NO_RECORDED_VALUE_MASK
 //
 enum DataPointFlags {
-  FLAG_NONE = 0;
+  // The zero value for the enum. Should not be used for comparisons.
+  // Instead use bitwise "and" with the appropriate mask as shown above.
+  FLAG_DO_NOT_USE = 0;
 
   // This DataPoint is valid but has no recorded value.  This value
   // SHOULD be used to reflect explicitly missing data in a series, as
   // for an equivalent to the Prometheus "staleness marker".
-  FLAG_NO_RECORDED_VALUE = 1;
+  FLAG_NO_RECORDED_VALUE_MASK = 1;
 
   // Bits 2-31 are reserved for future use.
 }