Restore updated documentation in validate.proto (#328)

To be merged once we're ready to ship all implementations conforming to
#320.

(Updates to the comments have been reverted in
#327)

Author: timostamm

proto/protovalidate/buf/validate/validate.proto

@@ -3276,10 +3276,16 @@ message StringRules {
   }];
 
   // `WellKnown` rules provide advanced constraints against common string
-  // patterns
+  // patterns.
   oneof well_known {
-    // `email` specifies that the field value must be a valid email address
-    // (addr-spec only) as defined by [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322#section-3.4.1).
+    // `email` specifies that the field value must be a valid email address, for
+    // example "[email protected]".
+    //
+    // Conforms to the definition for a valid email address from the [HTML standard](https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address).
+    // Note that this standard willfully deviates from [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322),
+    // which allows many unexpected forms of email addresses and will easily match
+    // a typographical error.
+    //
     // If the field value isn't a valid email address, an error message will be generated.
     //
     // ```proto
@@ -3301,10 +3307,18 @@ message StringRules {
       }
     ];
 
-    // `hostname` specifies that the field value must be a valid
-    // hostname as defined by [RFC 1034](https://datatracker.ietf.org/doc/html/rfc1034#section-3.5). This constraint doesn't support
-    // internationalized domain names (IDNs). If the field value isn't a
-    // valid hostname, an error message will be generated.
+    // `hostname` specifies that the field value must be a valid hostname, for
+    // example "foo.example.com".
+    //
+    // A valid hostname follows the rules below:
+    // - The name consists of one or more labels, separated by a dot (".").
+    // - Each label can be 1 to 63 alphanumeric characters.
+    // - A label can contain hyphens ("-"), but must not start or end with a hyphen.
+    // - The right-most label must not be digits only.
+    // - The name can have a trailing dot—for example, "foo.example.com.".
+    // - The name can be 253 characters at most, excluding the optional trailing dot.
+    //
+    // If the field value isn't a valid hostname, an error message will be generated.
     //
     // ```proto
     // message MyString {
@@ -3325,8 +3339,15 @@ message StringRules {
       }
     ];
 
-    // `ip` specifies that the field value must be a valid IP
-    // (v4 or v6) address, without surrounding square brackets for IPv6 addresses.
+    // `ip` specifies that the field value must be a valid IP (v4 or v6) address.
+    //
+    // IPv4 addresses are expected in the dotted decimal format—for example, "192.168.5.21".
+    // IPv6 addresses are expected in their text representation—for example, "::1",
+    // or "2001:0DB8:ABCD:0012::0".
+    //
+    // Both formats are well-defined in the internet standard [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986).
+    // Zone identifiers for IPv6 addresses (for example, "fe80::a%en1") are supported.
+    //
     // If the field value isn't a valid IP address, an error message will be
     // generated.
     //
@@ -3349,9 +3370,9 @@ message StringRules {
       }
     ];
 
-    // `ipv4` specifies that the field value must be a valid IPv4
-    // address. If the field value isn't a valid IPv4 address, an error message
-    // will be generated.
+    // `ipv4` specifies that the field value must be a valid IPv4 address—for
+    // example "192.168.5.21". If the field value isn't a valid IPv4 address, an
+    // error message will be generated.
     //
     // ```proto
     // message MyString {
@@ -3372,9 +3393,9 @@ message StringRules {
       }
     ];
 
-    // `ipv6` specifies that the field value must be a valid
-    // IPv6 address, without surrounding square brackets. If the field value is
-    // not a valid IPv6 address, an error message will be generated.
+    // `ipv6` specifies that the field value must be a valid IPv6 address—for
+    // example "::1", or "d7a:115c:a1e0:ab12:4843:cd96:626b:430b". If the field
+    // value is not a valid IPv6 address, an error message will be generated.
     //
     // ```proto
     // message MyString {
@@ -3395,8 +3416,11 @@ message StringRules {
       }
     ];
 
-    // `uri` specifies that the field value must be a valid URI as defined by
-    // [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-3).
+    // `uri` specifies that the field value must be a valid URI, for example
+    // "https://example.com/foo/bar?baz=quux#frag".
+    //
+    // URI is defined in the internet standard [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986).
+    // Zone Identifiers in IPv6 address literals are supported ([RFC 6874](https://datatracker.ietf.org/doc/html/rfc6874)).
     //
     // If the field value isn't a valid URI, an error message will be generated.
     //
@@ -3419,11 +3443,13 @@ message StringRules {
       }
     ];
 
-    // `uri_ref` specifies that the field value must be a valid URI Reference as
-    // defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-4.1).
+    // `uri_ref` specifies that the field value must be a valid URI Reference—either
+    // a URI such as "https://example.com/foo/bar?baz=quux#frag", or a Relative
+    // Reference such as "./foo/bar?query".
     //
-    // A URI Reference is either a [URI](https://datatracker.ietf.org/doc/html/rfc3986#section-3),
-    // or a [Relative Reference](https://datatracker.ietf.org/doc/html/rfc3986#section-4.2).
+    // URI, URI Reference, and Relative Reference are defined in the internet
+    // standard [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). Zone
+    // Identifiers in IPv6 address literals are supported ([RFC 6874](https://datatracker.ietf.org/doc/html/rfc6874)).
     //
     // If the field value isn't a valid URI Reference, an error message will be
     // generated.
@@ -3441,10 +3467,9 @@ message StringRules {
     }];
 
     // `address` specifies that the field value must be either a valid hostname
-    // as defined by [RFC 1034](https://datatracker.ietf.org/doc/html/rfc1034#section-3.5)
-    // (which doesn't support internationalized domain names or IDNs) or a valid
-    // IP (v4 or v6). If the field value isn't a valid hostname or IP, an error
-    // message will be generated.
+    // (for example, "example.com"), or a valid IP (v4 or v6) address (for example,
+    // "192.168.0.1", or "::1"). If the field value isn't a valid hostname or IP,
+    // an error message will be generated.
     //
     // ```proto
     // message MyString {
@@ -3512,10 +3537,10 @@ message StringRules {
       }
     ];
 
-    // `ip_with_prefixlen` specifies that the field value must be a valid IP (v4 or v6)
-    // address with prefix length. If the field value isn't a valid IP with prefix
-    // length, an error message will be generated.
-    //
+    // `ip_with_prefixlen` specifies that the field value must be a valid IP
+    // (v4 or v6) address with prefix length—for example, "192.168.5.21/16" or
+    // "2001:0DB8:ABCD:0012::F1/64". If the field value isn't a valid IP with
+    // prefix length, an error message will be generated.
     //
     // ```proto
     // message MyString {
@@ -3537,9 +3562,9 @@ message StringRules {
     ];
 
     // `ipv4_with_prefixlen` specifies that the field value must be a valid
-    // IPv4 address with prefix.
-    // If the field value isn't a valid IPv4 address with prefix length,
-    // an error message will be generated.
+    // IPv4 address with prefix length—for example, "192.168.5.21/16". If the
+    // field value isn't a valid IPv4 address with prefix length, an error
+    // message will be generated.
     //
     // ```proto
     // message MyString {
@@ -3561,7 +3586,7 @@ message StringRules {
     ];
 
     // `ipv6_with_prefixlen` specifies that the field value must be a valid
-    // IPv6 address with prefix length.
+    // IPv6 address with prefix length—for example, "2001:0DB8:ABCD:0012::F1/64".
     // If the field value is not a valid IPv6 address with prefix length,
     // an error message will be generated.
     //
@@ -3584,10 +3609,15 @@ message StringRules {
       }
     ];
 
-    // `ip_prefix` specifies that the field value must be a valid IP (v4 or v6) prefix.
+    // `ip_prefix` specifies that the field value must be a valid IP (v4 or v6)
+    // prefix—for example, "192.168.0.0/16" or "2001:0DB8:ABCD:0012::0/64".
+    //
+    // The prefix must have all zeros for the unmasked bits. For example,
+    // "2001:0DB8:ABCD:0012::0/64" designates the left-most 64 bits for the
+    // prefix, and the remaining 64 bits must be zero.
+    //
     // If the field value isn't a valid IP prefix, an error message will be
-    // generated. The prefix must have all zeros for the masked bits of the prefix (e.g.,
-    // `127.0.0.0/16`, not `127.0.0.1/16`).
+    // generated.
     //
     // ```proto
     // message MyString {
@@ -3609,9 +3639,14 @@ message StringRules {
     ];
 
     // `ipv4_prefix` specifies that the field value must be a valid IPv4
-    // prefix. If the field value isn't a valid IPv4 prefix, an error message
-    // will be generated. The prefix must have all zeros for the masked bits of
-    // the prefix (e.g., `127.0.0.0/16`, not `127.0.0.1/16`).
+    // prefix, for example "192.168.0.0/16".
+    //
+    // The prefix must have all zeros for the unmasked bits. For example,
+    // "192.168.0.0/16" designates the left-most 16 bits for the prefix,
+    // and the remaining 16 bits must be zero.
+    //
+    // If the field value isn't a valid IPv4 prefix, an error message
+    // will be generated.
     //
     // ```proto
     // message MyString {
@@ -3632,10 +3667,15 @@ message StringRules {
       }
     ];
 
-    // `ipv6_prefix` specifies that the field value must be a valid IPv6 prefix.
+    // `ipv6_prefix` specifies that the field value must be a valid IPv6 prefix—for
+    // example, "2001:0DB8:ABCD:0012::0/64".
+    //
+    // The prefix must have all zeros for the unmasked bits. For example,
+    // "2001:0DB8:ABCD:0012::0/64" designates the left-most 64 bits for the
+    // prefix, and the remaining 64 bits must be zero.
+    //
     // If the field value is not a valid IPv6 prefix, an error message will be
-    // generated. The prefix must have all zeros for the masked bits of the prefix
-    // (e.g., `2001:db8::/48`, not `2001:db8::1/48`).
+    // generated.
     //
     // ```proto
     // message MyString {
@@ -3656,10 +3696,16 @@ message StringRules {
       }
     ];
 
-    // `host_and_port` specifies the field value must be a valid host and port
-    // pair. The host must be a valid hostname or IP address while the port
-    // must be in the range of 0-65535, inclusive. IPv6 addresses must be delimited
-    // with square brackets (e.g., `[::1]:1234`).
+    // `host_and_port` specifies that the field value must be valid host/port
+    // pair—for example, "example.com:8080".
+    //
+    // The host can be one of:
+    //- An IPv4 address in dotted decimal format—for example, "192.168.5.21".
+    //- An IPv6 address enclosed in square brackets—for example, "[2001:0DB8:ABCD:0012::F1]".
+    //- A hostname—for example, "example.com".
+    //
+    // The port is separated by a colon. It must be non-empty, with a decimal number
+    // in the range of 0-65535, inclusive.
     bool host_and_port = 32 [
       (predefined).cel = {
         id: "string.host_and_port"