polish the godoc a little more

Author: Mengqi Yu

pkg/doc.go

@@ -51,13 +51,13 @@ system must be read for each Reconciler.
 
 Webhook
 
-Admission Webhook is a mechanism for extending kubernetes APIs. The API server will send AdmissionRequests to
+Admission Webhooks are a mechanism for extending kubernetes APIs. The API server will send AdmissionRequests to
 the webhooks according to the configured target event type (object Create, Update, Delete). The webhooks may
 mutate and (or) validate the object embedded in the AdmissionReview requests.
 
 There are 2 types of admission webhook: mutating and validating admission webhook.
-Mutating webhook is used to mutate a core API object or a CRD instance before the API server admit it.
-Validting webhook is used to validate if a core API object or a CRD instance meet certain requirements.
+Mutating webhook is used to mutate a core API object or a CRD instance before the API server admits it.
+Validating webhook is used to validate if an object meets certain requirements.
 
 * Admission Webhooks require Handler(s) to be provided to process the received AdmissionReview requests.
 

pkg/webhook/admission/builder/doc.go

@@ -17,7 +17,9 @@ limitations under the License.
 /*
 Package builder provides methods to build admission webhooks.
 
-For most users, we recommend to use Operations and ForType to construct a webhook.
+For most users, we recommend to use Operations and ForType to construct a webhook,
+since it is more intuitive and easier to pass the target operations to Operations method and
+a empty target object to ForType method than passing a complex RuleWithOperations struct to Rules method.
 
 	webhook1, err := NewWebhookBuilder().
 		Mutating().
@@ -41,8 +43,27 @@ For most users, we recommend to use Operations and ForType to construct a webhoo
 		// handle error
 	}
 
-Note: To build a webhook for CRD, you need to ensure the manager is
-constructed from the scheme that understands your CRD.
+Note: To build a webhook for a CRD, you need to ensure the manager uses the scheme that understands your CRD.
+This is necessary, because if the scheme doesn't understand your CRD types, the decoder won't be able to decode
+the CR object from the admission review request.
+
+The following snippet shows how to register CRD types with manager's scheme.
+
+	mgr, err := manager.New(cfg, manager.Options{})
+	if err != nil {
+		// handle error
+	}
+	// SchemeGroupVersion is group version used to register these objects
+	SchemeGroupVersion = schema.GroupVersion{Group: "crew.k8s.io", Version: "v1"}
+	// SchemeBuilder is used to add go types to the GroupVersionKind scheme
+	SchemeBuilder = &scheme.Builder{GroupVersion: SchemeGroupVersion}
+	// Register your CRD types.
+	SchemeBuilder.Register(&Kraken{}, &KrakenList{})
+	// Register your CRD types with the manager's scheme.
+	err = SchemeBuilder.AddToScheme(mgr.GetScheme())
+	if err != nil {
+		// handle error
+	}
 
 There are more options for configuring a webhook. e.g. Name, Path, FailurePolicy, NamespaceSelector.
 Here is another example:

pkg/webhook/admission/doc.go

@@ -43,13 +43,13 @@ The following snippet is an example implementation of mutating handler.
 		return admission.PatchResponse(pod, copy)
 	}
 
-	// InjectClient injects the client into the Handler
+	// InjectClient is called by the Manager and provides a client.Client to the Mutator instance.
 	func (m *Mutator) InjectClient(c client.Client) error {
 		h.client = c
 		return nil
 	}
 
-	// InjectDecoder injects the decoder into the Handler
+	// InjectDecoder is called by the Manager and provides a types.Decoder to the Mutator instance.
 	func (m *Mutator) InjectDecoder(d types.Decoder) error {
 		h.decoder = d
 		return nil
@@ -80,13 +80,13 @@ The following snippet is an example implementation of validating handler.
 		return admission.ValidationResponse(allowed, reason)
 	}
 
-	// InjectClient injects the client into the Handler
+	// InjectClient is called by the Manager and provides a client.Client to the Validator instance.
 	func (v *Validator) InjectClient(c client.Client) error {
 		h.client = c
 		return nil
 	}
 
-	// InjectDecoder injects the decoder into the Handler
+	// InjectDecoder is called by the Manager and provides a types.Decoder to the Validator instance.
 	func (v *Validator) InjectDecoder(d types.Decoder) error {
 		h.decoder = d
 		return nil