Add documentation for optionalfields linter

Author: JoelSpeed

README.md

@@ -279,6 +279,42 @@ lintersConfig:
 
 The `nophase` linter checks that the fields in the API types don't contain a 'Phase', or any field which contains 'Phase' as a substring, e.g MachinePhase.
 
+## OptionalFields
+
+The `optionalfields` linter checks that all fields marked as optional adhere to being pointers and having the `omitempty` value in their `json` tag where appropriate.
+
+If you prefer to avoid pointers where possible, the linter can be configured with the `WhenRequired` preference to determine, based on the serialization and valid values for the field, whether the field should be a pointer or not.
+For example, an optional 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.
+
+In certain use cases, it can be desirable to not omit optional 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:
+  optionalFields:
+    pointers:
+      preference: Always | WhenRequired # Whether to always require pointers, or only when required. Defaults to `Always`.
+      policy: SuggestFix | Warn # The policy for pointers in optional fields. Defaults to `SuggestFix`.
+    omitempty:
+        policy: SuggestFix | Warn | Ignore # The policy for omitempty in optional fields. Defaults to `SuggestFix`.
+```
+
+### Fixes
+
+The `optionalfields` linter can automatically fix fields that are marked as optional, that are either not pointers or do not have the `omitempty` 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.
+
+If you prefer not to suggest fixes for pointers in optional fields, you can change the `pointers.policy` to `Warn`.
+
+If you prefer not to suggest fixes for `omitempty` in optional fields, you can change the `omitempty.policy` to `Warn` or `Ignore`.
+
+When the `pointers.preference` is set to `WhenRequired`, the linter will suggest to add the pointer to the field only when the field zero value is a valid value for the field.
+When the field zero value is not a valid value for the field, the linter will suggest to remove the pointer from the field.
+
+When the `pointers.preference` is set to `Always`, the linter will always suggest to add the pointer to the field, regardless of the validity of the zero value of the field.
+
 ## OptionalOrRequired
 
 The `optionalorrequired` linter checks that all fields in the API types are either optional or required, and are marked explicitly as such.

pkg/analysis/optionalfields/doc.go

@@ -15,5 +15,16 @@ limitations under the License.
 */
 
 /*
- */
+optionalfields is a linter to check that fields that are marked as optional are marshalled properly depending on the configured policies.
+
+By default, all optional fields should be pointers and have omitempty tags. The exception to this would be arrays and maps where the empty value can be omitted without the need for a pointer.
+
+However, where the zero value for a field is not a valid value (e.g. the empty string, or 0), the field does not need to be a pointer as the zero value could never be admitted.
+In this case, the field may not need to be a pointer, and, with the WhenRequired preference, the linter will point out where the fields do not need to be pointers.
+
+Structs are also inspected to determine if they require a pointer.
+If a struct has any required fields, or a minimum numebr of properties, then fields leveraging the struct should be pointers.
+
+Optional structs do not always need to be pointers, but may be marshalled as `{}` because the JSON marshaller in Go cannot determine whether a struct is empty or not.
+*/
 package optionalfields