fix documentation about requiredfields

Author: nayuta723

docs/linters.md

@@ -289,25 +289,39 @@ It will also remove the secondary marker where both the preferred and secondary
 
 ## RequiredFields
 
-The `requiredfields` linter checks that fields that are marked as required, follow the convention of not being pointers,
-and not having an `omitempty` value in their `json` tag.
+The `requiredfields` linter checks that all fields marked as required adhere to having `omitempty` tags and being pointers where the zero value is an acceptable value.
+Currently `omitzero` is handled only for fields with struct type.
+
+If you prefer to avoid pointers where possible, the linter can be configured to determine, based on the validation constraints for the field, whether the field should be a pointer or not.
+For example:
+- a required string with a non-zero minimum length does not need to be a pointer, as the zero value is not valid, and it is safe for the Go marshaller to omit the empty value.
+- a required struct having omitzero json tag with validation constraints that make the zero value invalid does not need to be a pointer, as the zero value is not valid, and it is safe for the Go marshaller to omit the empty value.
+
+In certain use cases, it can be desirable to not omit required fields from the serialized form of the object.
+In this case, the `omitempty` policy can be set to `Ignore`, and the linter will ensure that the zero value of the object is an acceptable value for the field.
 
 ### Configuration
 
 ```yaml
 lintersConfig:
   requiredfields:
-    pointerPolicy: Warn | SuggestFix # The policy for pointers in required fields. Defaults to `SuggestFix`.
+    pointers:
+      policy: SuggestFix | Warn # The policy for pointers in required fields. Defaults to `SuggestFix`.
+    omitempty:
+      policy: SuggestFix | Warn | Ignore # The policy for omitempty in required fields. Defaults to `SuggestFix`.
+    omitzero:
+      policy: SuggestFix | Warn | Forbid # The policy for omitzero in required fields. Defaults to `SuggestFix`.
 ```
 
 ### Fixes
 
-The `requiredfields` linter can automatically fix fields that are marked as required, but are pointers.
+The `requiredfields` linter can automatically fix fields that are marked as required, that are either not pointers when they should be or do not have the `omitempty` or `omitzero` value in their `json` tag.
+It will suggest to add the pointer to the field, and update the `json` tag to include the `omitempty` value or, for struct fields specifically, it will suggest to remove the pointer to the field, and update the `json` tag to include the `omitzero` value.
 
-It will suggest to remove the pointer from the field, and update the `json` tag to remove the `omitempty` value.
+If you prefer not to suggest fixes for pointers in required fields, you can change the `pointers.policy` to `Warn`.
 
-If you prefer not to suggest fixes for pointers in required fields, you can change the `pointerPolicy` to `Warn`.
-The linter will then only suggest to remove the `omitempty` value from the `json` tag.
+If you prefer not to suggest fixes for `omitempty` in required fields, you can change the `omitempty.policy` to `Warn` or `Ignore`.
+If you prefer not to suggest fixes for `omitzero` in required fields, you can change the `omitzero.policy` to `Warn` and also not to consider `omitzero` policy at all, it can be set to `Forbid`.
 
 ## SSATags
 

pkg/analysis/requiredfields/doc.go

@@ -15,13 +15,12 @@ limitations under the License.
 */
 
 /*
-requiredFields is a linter to check that fields that are marked as required are not pointers, and do not have the omitempty tag.
-The linter will check for fields that are marked as required using the +required marker, or the +kubebuilder:validation:Required marker.
+requiredfields is a linter to check that fields that are marked as required are marshalled properly depending on the configured policies.
 
-The linter will suggest to remove the omitempty tag from fields that are marked as required, but have the omitempty tag.
-The linter will suggest to remove the pointer type from fields that are marked as required.
+By default, all required fields should have omitempty tags and be pointers where the zero value is an acceptable value. The exception to this would be where the zero value for a field is not a valid value, in which case the field does not need to be a pointer.
 
-If you have a large, existing codebase, you may not want to automatically fix all of the pointer issues.
-In this case, you can configure the linter not to suggest fixing the pointer issues by setting the `pointerPolicy` option to `Warn`.
+However, where the zero value for a field is a valid value (e.g. the empty string, or 0), the field should be a pointer to distinguish between unset and zero value states.
+
+Required fields should always have omitempty tags to prevent "mess" in the encoded object, regardless of whether they are pointers.
 */
 package requiredfields