address comments

Author: Mengqi Yu

pkg/doc.go

@@ -51,9 +51,10 @@ system must be read for each Reconciler.
 
 Webhook
 
-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.
+Admission Webhooks are a mechanism for extending kubernetes APIs. Webhooks can be configured with target
+event type (object Create, Update, Delete), the API server will send AdmissionRequests to them
+when certain events happen. The webhooks may mutate and (or) validate the object embedded in
+the AdmissionReview requests and send back the response to the API server.
 
 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 admits it.

pkg/webhook/admission/builder/doc.go

@@ -17,9 +17,7 @@ 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,
-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.
+The following are 2 examples for building mutating webhook and validating webhook.
 
 	webhook1, err := NewWebhookBuilder().
 		Mutating().
@@ -82,7 +80,11 @@ Here is another example:
 		// handle error
 	}
 
-For some advanced use cases like subresources, etc., you can directly use Rules instead of use Operations and ForType.
+For most users, we recommend to use Operations and ForType instead of Rules 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.
+
+Rules may be useful for some more advanced use cases like subresources, wildcard resources etc.
 Here is an example:
 
 	webhook4, err := NewWebhookBuilder().

pkg/webhook/doc.go

@@ -17,7 +17,7 @@ limitations under the License.
 /*
 Package webhook provides methods to build and bootstrap a webhook server.
 
-Currently, it only supports hosting admission webhooks.
+Currently, it only supports admission webhooks. It will support CRD conversion webhooks in the near future.
 
 Build webhooks