docs: field name and minor formatting fixes (#3057)

Signed-off-by: Peter Jausovec <peter.jausovec@solo.io>

security/v1/authorization_policy.proto

@@ -517,7 +517,7 @@ message AuthorizationPolicy {
     // the authorization decision to it.
     //
     // The following authorization policy applies to an ingress gateway and delegates the authorization check to a named extension
-    // "my-custom-authz" if the request path has prefix "/admin/".
+    // `my-custom-authz` if the request path has prefix `/admin/`.
     //
     // ```yaml
     // apiVersion: security.istio.io/v1beta1
@@ -561,18 +561,18 @@ message AuthorizationPolicy {
 //
 // Any string field in the rule supports Exact, Prefix, Suffix and Presence match:
 //
-// - Exact match: "abc" will match on value "abc".
-// - Prefix match: "abc*" will match on value "abc" and "abcd".
-// - Suffix match: "*abc" will match on value "abc" and "xabc".
-// - Presence match: "*" will match when value is not empty.
+// - Exact match: `abc` will match on value `abc`.
+// - Prefix match: `abc*` will match on value `abc` and `abcd`.
+// - Suffix match: `*abc` will match on value `abc` and `xabc`.
+// - Presence match: `*` will match when value is not empty.
 message Rule {
   // From includes a list of sources.
   message From {
     // Source specifies the source of a request.
     Source source = 1;
   }
 
-  // Optional. from specifies the source of a request.
+  // Optional. `from` specifies the source of a request.
   //
   // If not set, any source is allowed.
   repeated From from = 1;
@@ -583,12 +583,12 @@ message Rule {
     Operation operation = 1;
   }
 
-  // Optional. to specifies the operation of a request.
+  // Optional. `to` specifies the operation of a request.
   //
   // If not set, any operation is allowed.
   repeated To to = 2;
 
-  // Optional. when specifies a list of additional conditions of a request.
+  // Optional. `when` specifies a list of additional conditions of a request.
   //
   // If not set, any condition is allowed.
   repeated Condition when = 3;
@@ -597,8 +597,8 @@ message Rule {
 // Source specifies the source identities of a request. Fields in the source are
 // ANDed together.
 //
-// For example, the following source matches if the principal is "admin" or "dev"
-// and the namespace is "prod" or "test" and the ip is not "203.0.113.4".
+// For example, the following source matches if the principal is `admin` or `dev`
+// and the namespace is `prod` or `test` and the ip is not `203.0.113.4`.
 //
 // ```yaml
 // principals: ["admin", "dev"]
@@ -635,20 +635,20 @@ message Source {
   // Optional. A list of negative match of namespaces.
   repeated string not_namespaces = 7;
 
-  // Optional. A list of IP blocks, populated from the source address of the IP packet. Single IP (e.g. "203.0.113.4") and
-  // CIDR (e.g. "203.0.113.0/24") are supported. This is the same as the `source.ip` attribute.
+  // Optional. A list of IP blocks, populated from the source address of the IP packet. Single IP (e.g. `203.0.113.4`) and
+  // CIDR (e.g. `203.0.113.0/24`) are supported. This is the same as the `source.ip` attribute.
   //
   // If not set, any IP is allowed.
   repeated string ip_blocks = 4;
 
   // Optional. A list of negative match of IP blocks.
   repeated string not_ip_blocks = 8;
 
-  // Optional. A list of IP blocks, populated from X-Forwarded-For header or proxy protocol.
-  // To make use of this field, you must configure the numTrustedProxies field of the gatewayTopology under the meshConfig
+  // Optional. A list of IP blocks, populated from `X-Forwarded-For` header or proxy protocol.
+  // To make use of this field, you must configure the `numTrustedProxies` field of the `gatewayTopology` under the `meshConfig`
   // when you install Istio or using an annotation on the ingress gateway.  See the documentation here:
   // [Configuring Gateway Network Topology](https://istio.io/latest/docs/ops/configuration/traffic-management/network-topologies/).
-  // Single IP (e.g. "203.0.113.4") and CIDR (e.g. "203.0.113.0/24") are supported.
+  // Single IP (e.g. `203.0.113.4`) and CIDR (e.g. `203.0.113.0/24`) are supported.
   // This is the same as the `remote.ip` attribute.
   //
   // If not set, any IP is allowed.
@@ -661,8 +661,8 @@ message Source {
 // Operation specifies the operations of a request. Fields in the operation are
 // ANDed together.
 //
-// For example, the following operation matches if the host has suffix ".example.com"
-// and the method is "GET" or "HEAD" and the path doesn't have prefix "/admin".
+// For example, the following operation matches if the host has suffix `.example.com`
+// and the method is `GET` or `HEAD` and the path doesn't have prefix `/admin`.
 //
 // ```yaml
 // hosts: ["*.example.com"]
@@ -689,7 +689,7 @@ message Operation {
   repeated string not_ports = 6;
 
   // Optional. A list of methods as specified in the HTTP request.
-  // For gRPC service, this will always be "POST".
+  // For gRPC service, this will always be `POST`.
   //
   // If not set, any method is allowed. Must be used only with HTTP.
   repeated string methods = 3;
@@ -699,7 +699,7 @@ message Operation {
 
   // Optional. A list of paths as specified in the HTTP request. See the [Authorization Policy Normalization](https://istio.io/latest/docs/reference/config/security/normalization/)
   // for details of the path normalization.
-  // For gRPC service, this will be the fully-qualified name in the form of "/package.service/method".
+  // For gRPC service, this will be the fully-qualified name in the form of `/package.service/method`.
   //
   // If not set, any path is allowed. Must be used only with HTTP.
   repeated string paths = 4;
@@ -715,10 +715,10 @@ message Condition {
   string key = 1 [(google.api.field_behavior) = REQUIRED];
 
   // Optional. A list of allowed values for the attribute.
-  // Note: at least one of values or not_values must be set.
+  // Note: at least one of `values` or `notValues` must be set.
   repeated string values = 2;
 
   // Optional. A list of negative match of values for the attribute.
-  // Note: at least one of values or not_values must be set.
+  // Note: at least one of `values` or `notValues` must be set.
   repeated string not_values = 3;
 }