Merge pull request #2529 from sayantani11/issue2520

📖Add info about markers

Author: k8s-ci-robot

docs/book/src/reference/markers.md

@@ -15,6 +15,19 @@ a marker name, optionally followed by some marker specific configuration:
 // +kubebuilder:printcolumn:JSONPath=".status.replicas",name=Replicas,type=string
 ```
 
+<aside class="note">
+<h1>difference between `// +optional` and `// +kubebuilder:validation:Optional`</h1>
+
+ Controller-gen supports both (see the output of `controller-gen crd -www`). `+kubebuilder:validation:Optional` and `+optional` can be applied to fields.
+
+ But `+kubebuilder:validation:Optional` can also be applied at the package level such that it applies to every field in the package.
+
+ If you're using controller-gen only then they're redundant, but if you're using other generators or you want developers that need to  build their own clients for your API, you'll want to also include `+optional`.
+
+ The most reliable way in 1.x to get `+optional` is `omitempty`.
+
+</aside>
+
 See each subsection for information about different types of code and YAML
 generation.