docs: clean up matcher docs and make it consistent (#39919)

## Description

This PR have some cleanup in metadata matcher proto docs for
consistency. We are using the note annotations and the backticks
inconsistently throughout right now.

---

**Commit Message:** docs: clean up metadata matcher docs and make it
consistent
**Additional Description:** Minor clean up for added clarity on the
metadata matcher docs.
**Risk Level:** N/A
**Testing:** N/A
**Docs Changes:** N/A
**Release Notes:** N/A

---------

Signed-off-by: Rohit Agrawal <[email protected]>
Co-authored-by: phlax <[email protected]>

Mirrored from https://github.com/envoyproxy/envoy @ 70880edde9c916318de0ab986daf9ea4d21a917a

Author: update-envoy[bot]

envoy/config/common/matcher/v3/matcher.proto

@@ -95,7 +95,7 @@ message Matcher {
         // A list of predicates to be AND-ed together.
         PredicateList and_matcher = 3;
 
-        // The invert of a predicate
+        // The inverse of a predicate
         Predicate not_matcher = 4;
       }
     }
@@ -148,8 +148,8 @@ message Matcher {
     MatcherTree matcher_tree = 2;
   }
 
-  // Optional OnMatch to use if the matcher failed.
-  // If specified, the OnMatch is used, and the matcher is considered
+  // Optional ``OnMatch`` to use if the matcher failed.
+  // If specified, the ``OnMatch`` is used, and the matcher is considered
   // to have matched.
   // If not specified, the matcher is considered not to have matched.
   OnMatch on_no_match = 3;
@@ -215,9 +215,9 @@ message HttpHeadersMatch {
 //
 // .. attention::
 //
-//   Searching for patterns in HTTP body is potentially cpu intensive. For each specified pattern, http body is scanned byte by byte to find a match.
+//   Searching for patterns in HTTP body is potentially CPU-intensive. For each specified pattern, HTTP body is scanned byte by byte to find a match.
 //   If multiple patterns are specified, the process is repeated for each pattern. If location of a pattern is known, ``bytes_limit`` should be specified
-//   to scan only part of the http body.
+//   to scan only part of the HTTP body.
 message HttpGenericBodyMatch {
   message GenericTextMatch {
     oneof rule {

envoy/type/matcher/v3/metadata.proto

@@ -16,11 +16,11 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: Metadata matcher]
 
-// MetadataMatcher provides a general interface to check if a given value is matched in
-// :ref:`Metadata <envoy_v3_api_msg_config.core.v3.Metadata>`. It uses `filter` and `path` to retrieve the value
-// from the Metadata and then check if it's matched to the specified value.
+// ``MetadataMatcher`` provides a general interface to check if a given value is matched in
+// :ref:`Metadata <envoy_v3_api_msg_config.core.v3.Metadata>`. It uses ``filter`` and ``path`` to retrieve the value
+// from the ``Metadata`` and then check if it's matched to the specified value.
 //
-// For example, for the following Metadata:
+// For example, for the following ``Metadata``:
 //
 // .. code-block:: yaml
 //
@@ -41,8 +41,8 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 //                      - string_value: m
 //                      - string_value: n
 //
-// The following MetadataMatcher is matched as the path [a, b, c] will retrieve a string value "pro"
-// from the Metadata which is matched to the specified prefix match.
+// The following ``MetadataMatcher`` is matched as the path ``[a, b, c]`` will retrieve a string value ``pro``
+// from the ``Metadata`` which is matched to the specified prefix match.
 //
 // .. code-block:: yaml
 //
@@ -55,7 +55,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 //      string_match:
 //        prefix: pr
 //
-// The following MetadataMatcher is matched as the code will match one of the string values in the
+// The following ``MetadataMatcher`` is matched as the code will match one of the string values in the
 // list at the path [a, t].
 //
 // .. code-block:: yaml
@@ -70,7 +70,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 //          string_match:
 //            exact: m
 //
-// An example use of MetadataMatcher is specifying additional metadata in envoy.filters.http.rbac to
+// An example use of ``MetadataMatcher`` is specifying additional metadata in ``envoy.filters.http.rbac`` to
 // enforce access control based on dynamic metadata in a request. See :ref:`Permission
 // <envoy_v3_api_msg_config.rbac.v3.Permission>` and :ref:`Principal
 // <envoy_v3_api_msg_config.rbac.v3.Principal>`.
@@ -79,28 +79,30 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 message MetadataMatcher {
   option (udpa.annotations.versioning).previous_message_type = "envoy.type.matcher.MetadataMatcher";
 
-  // Specifies the segment in a path to retrieve value from Metadata.
-  // Note: Currently it's not supported to retrieve a value from a list in Metadata. This means that
-  // if the segment key refers to a list, it has to be the last segment in a path.
+  // Specifies the segment in a path to retrieve value from ``Metadata``.
+  //
+  // .. note::
+  //   Currently it's not supported to retrieve a value from a list in ``Metadata``. This means that
+  //   if the segment key refers to a list, it has to be the last segment in a path.
   message PathSegment {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.type.matcher.MetadataMatcher.PathSegment";
 
     oneof segment {
       option (validate.required) = true;
 
-      // If specified, use the key to retrieve the value in a Struct.
+      // If specified, use the key to retrieve the value in a ``Struct``.
       string key = 1 [(validate.rules).string = {min_len: 1}];
     }
   }
 
-  // The filter name to retrieve the Struct from the Metadata.
+  // The filter name to retrieve the ``Struct`` from the ``Metadata``.
   string filter = 1 [(validate.rules).string = {min_len: 1}];
 
-  // The path to retrieve the Value from the Struct.
+  // The path to retrieve the ``Value`` from the ``Struct``.
   repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}];
 
-  // The MetadataMatcher is matched if the value retrieved by path is matched to this value.
+  // The ``MetadataMatcher`` is matched if the value retrieved by path is matched to this value.
   ValueMatcher value = 3 [(validate.rules).message = {required: true}];
 
   // If true, the match result will be inverted.