docs: change note annotation and reword the metadata docs (envoyproxy#39246)

Signed-off-by: Rohit Agrawal <rohit.agrawal@databricks.com>

Author: agrawroh

api/envoy/type/metadata/v3/metadata.proto

@@ -14,10 +14,10 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: Metadata]
 
-// MetadataKey provides a general interface using ``key`` and ``path`` to retrieve value from
-// :ref:`Metadata <envoy_v3_api_msg_config.core.v3.Metadata>`.
+// MetadataKey provides a way to retrieve values from
+// :ref:`Metadata <envoy_v3_api_msg_config.core.v3.Metadata>` using a ``key`` and a ``path``.
 //
-// For example, for the following Metadata:
+// For example, consider the following Metadata:
 //
 // .. code-block:: yaml
 //
@@ -28,7 +28,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 //          xyz:
 //            hello: envoy
 //
-// The following MetadataKey will retrieve a string value "bar" from the Metadata.
+// The following MetadataKey would retrieve the string value "bar" from the Metadata:
 //
 // .. code-block:: yaml
 //
@@ -40,34 +40,36 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 message MetadataKey {
   option (udpa.annotations.versioning).previous_message_type = "envoy.type.metadata.v2.MetadataKey";
 
-  // Specifies the segment in a path to retrieve value from Metadata.
-  // Currently it is only supported to specify the key, i.e. field name, as one segment of a path.
+  // Specifies a segment in a path for retrieving values from Metadata.
+  // Currently, only key-based segments (field names) are supported.
   message PathSegment {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.type.metadata.v2.MetadataKey.PathSegment";
 
     oneof segment {
       option (validate.required) = true;
 
-      // If specified, use the key to retrieve the value in a Struct.
+      // If specified, use this key to retrieve the value in a Struct.
       string key = 1 [(validate.rules).string = {min_len: 1}];
     }
   }
 
-  // The key name of Metadata to retrieve the Struct from the metadata.
-  // Typically, it represents a builtin subsystem or custom extension.
+  // The key name of the Metadata from which to retrieve the Struct.
+  // This typically represents a builtin subsystem or custom extension.
   string key = 1 [(validate.rules).string = {min_len: 1}];
 
-  // The path to retrieve the Value from the Struct. It can be a prefix or a full path,
-  // e.g. ``[prop, xyz]`` for a struct or ``[prop, foo]`` for a string in the example,
-  // which depends on the particular scenario.
+  // The path used to retrieve a specific Value from the Struct.
+  // This can be either a prefix or a full path, depending on the use case.
+  // For example, ``[prop, xyz]`` would retrieve a struct or ``[prop, foo]`` would retrieve a string
+  // in the example above.
   //
-  // Note: Due to that only the key type segment is supported, the path can not specify a list
-  // unless the list is the last segment.
+  // .. note::
+  //   Since only key-type segments are supported, a path cannot specify a list
+  //   unless the list is the last segment.
   repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}];
 }
 
-// Describes what kind of metadata.
+// Describes different types of metadata sources.
 message MetadataKind {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.type.metadata.v2.MetadataKind";