Update documentation.

proto/protovalidate/buf/validate/validate.proto

@@ -4772,18 +4772,60 @@ message Violations {
 message Violation {
   // `field` is a machine-readable path to the field that failed validation.
   // This could be a nested field, in which case the path will include all the parent fields leading to the actual field that caused the violation.
+  //
+  // For example, consider the following message:
+  //
+  // ```proto
+  // message Message {
+  //   bool a = 1 [(buf.validate.field).required = true];
+  // }
+  // ```
+  //
+  // It could produce the following violation:
+  //
+  // ```textproto
+  // violation {
+	//   field { element { field_number: 1, field_name: "a", field_type: 8 } }
+	//   ...
+	// }
+  // ```
   optional FieldPath field = 5;
 
   // `rule` is a machine-readable path that points to the specific constraint rule that failed validation.
   // This will be a nested field starting from the FieldConstraints of the field that failed validation.
-  // This field is not present when there is no corresponding rule field, e.g. for custom constraints.
+  // For custom constraints, this will provide the path of the constraint, e.g. `cel[0]`.
+  // 
+  // For example, consider the following message:
+  //
+  // ```proto
+  // message Message {
+  //   bool a = 1 [(buf.validate.field).required = true];
+  //   bool b = 2 [(buf.validate.field).cel = {
+  //     id: "custom_constraint",
+  //     expression: "!this ? 'b must be true': ''"
+  //   }]
+  // }
+  // ```
+  //
+  // It could produce the following violations:
+  //
+  // ```textproto
+  // violation {
+	//   rule { element { field_number: 25, field_name: "required", field_type: 8 } }
+	//   ...
+	// }
+  // violation {
+	//   rule { element { field_number: 23, field_name: "cel", field_type: 11, index: 0 } }
+	//   ...
+	// }
+  // ```
   optional FieldPath rule = 6;
 
   // `field_path` is a human-readable identifier that points to the specific field that failed the validation.
   // This could be a nested field, in which case the path will include all the parent fields leading to the actual field that caused the violation.
   //
   // Deprecated: use the `field` instead.
-  optional string field_path = 1;
+  optional string field_path = 1 [deprecated = true];
 
   // `constraint_id` is the unique identifier of the `Constraint` that was not fulfilled.
   // This is the same `id` that was specified in the `Constraint` message, allowing easy tracing of which rule was violated.
@@ -4809,7 +4851,7 @@ message FieldPath {
 // `FieldPathElement` provides enough information to nest through a single protobuf field.
 //
 // If the selected field is a map or repeated field, the `subscript` value selects a specific element from it.
-// A path that refers to a map or repeated field and not an element under it will not have a `subscript` value.
+// A path that refers to a value nested under a map key or repeated field index will have a `subscript` value.
 // The `field_type` field allows unambiguous resolution of a field even if descriptors are not available.
 message FieldPathElement {
   // `field_number` is the field number this path element refers to.
@@ -4822,7 +4864,13 @@ message FieldPathElement {
   // `field_type` specifies the type of this field. When using reflection, this value is not needed.
   //
   // This value is provided to make it possible to traverse unknown fields through wire data.
-  // When traversing wire data, be mindful of both packed and delimited encoding schemes.
+  // When traversing wire data, be mindful of both packed[1] and delimited[2] encoding schemes.
+  //
+  // [1]: https://protobuf.dev/programming-guides/encoding/#packed
+  // [2]: https://protobuf.dev/programming-guides/encoding/#groups
+  //
+  // N.B.: Although groups are deprecated, the corresponding delimited encoding scheme is not, and
+  // can be explicitly used in Protocol Buffers 2023 Edition.
   optional google.protobuf.FieldDescriptorProto.Type field_type = 3;
 
   // `subscript` contains a repeated index or map key, if this path element nests into a repeated or map field.