Address feedback

exp/runtime/catalog/openapi.go

@@ -40,11 +40,11 @@ func (c *Catalog) OpenAPI(version string) (*spec3.OpenAPI, error) {
 				Description: "This document defines the Open API specification of the services that Cluster API runtime is going " +
 					"to call while managing the Cluster's lifecycle.\n" +
 					"\n" +
-					"Services described in this specification are also referred as Runtime Hooks, given that they allow " +
-					"external components to hook-in the cluster's lifecycle. Instead, the components implementing handlers " +
-					"for Runtime Hooks calls are referred as Runtime Extensions..\n" +
+					"Services described in this specification are also referred to as Runtime Hooks, given that they allow " +
+					"external components to hook-in the cluster's lifecycle. The corresponding components implementing handlers " +
+					"for Runtime Hooks calls are referred to as Runtime Extensions.\n" +
 					"\n" +
-					"More info are available in the [Cluster API book](https://cluster-api.sigs.k8s.io/).",
+					"More information is available in the [Cluster API book](https://cluster-api.sigs.k8s.io/).",
 				Title: "Cluster API - Runtime SDK",
 				License: &spec.License{
 					Name: "Apache 2.0",
@@ -97,7 +97,7 @@ func addHookAndTypesToOpenAPI(openAPI *spec3.OpenAPI, c *Catalog, gvh GroupVersi
 			ParameterProps: spec3.ParameterProps{
 				Name:        "name",
 				In:          "path",
-				Description: "The handler name. Handlers for the same hook within a single external component implementing RuntimeExtension must have different names",
+				Description: "The handler name. Handlers for the same hook within a single external component implementing Runtime Extensions must have different names",
 				Required:    true,
 				Schema: &spec.Schema{
 					SchemaProps: spec.SchemaProps{
@@ -139,7 +139,7 @@ func addHookAndTypesToOpenAPI(openAPI *spec3.OpenAPI, c *Catalog, gvh GroupVersi
 	responseTypeName := typeName(responseType, responseGVK)
 	operation.Responses.StatusCodeResponses[http.StatusOK] = &spec3.Response{
 		ResponseProps: spec3.ResponseProps{
-			Description: "OK The HTTP 200 OK success status response code indicates that the request has ben processed. Runtime Extensions authors must use status and message to return processing outcomes.",
+			Description: "Status code 200 indicates that the request has been processed successfully. Runtime Extension authors must use fields in the response like e.g. status and message to return processing outcomes.",
 			Content:     createContent(responseTypeName),
 		},
 	}

exp/runtime/hooks/api/v1alpha1/discovery_types.go

@@ -92,13 +92,13 @@ func Discovery(*DiscoveryRequest, *DiscoveryResponse) {}
 func init() {
 	catalogBuilder.RegisterHook(Discovery, &runtimecatalog.HookMeta{
 		Tags:    []string{"Discovery"},
-		Summary: "Cluster API Runtime will call this hook when a ExtensionConfig is reconciled",
-		Description: "Cluster API Runtime will call this hook when a ExtensionConfig is reconciled. " +
+		Summary: "Cluster API Runtime will call this hook when an ExtensionConfig is reconciled",
+		Description: "Cluster API Runtime will call this hook when an ExtensionConfig is reconciled. " +
 			"Runtime Extension implementers must use this hook to inform the Cluster API runtime about all the handlers " +
-			"that are defined in an external component implementing Runtime Extension.\n" +
+			"that are defined in an external component implementing Runtime Extensions.\n" +
 			"\n" +
 			"Notes:\n" +
-			"- When using Runtime SDK utils, an handler for this hook is automatically generated",
+			"- When using Runtime SDK utils, a handler for this hook is automatically generated",
 		Singleton: true,
 	})
 }

exp/runtime/hooks/api/v1alpha1/lifecyclehooks_types.go

@@ -181,7 +181,7 @@ func BeforeClusterDelete(*BeforeClusterDeleteRequest, *BeforeClusterDeleteRespon
 func init() {
 	catalogBuilder.RegisterHook(BeforeClusterCreate, &runtimecatalog.HookMeta{
 		Tags:    []string{"Lifecycle Hooks"},
-		Summary: "Cluster API Runtime will call this hook before Cluster's topology is created.",
+		Summary: "Cluster API Runtime will call this hook before a Cluster's topology is created",
 		Description: "Cluster API Runtime will call this hook after the Cluster is created by the user and immediately before " +
 			"all the objects which are part of a Cluster's topology are going to be created.\n" +
 			"\n" +
@@ -194,8 +194,8 @@ func init() {
 
 	catalogBuilder.RegisterHook(AfterControlPlaneInitialized, &runtimecatalog.HookMeta{
 		Tags:    []string{"Lifecycle Hooks"},
-		Summary: "Cluster API Runtime will call this hook after the Control Plane is initialized for the first time",
-		Description: "Cluster API Runtime will call this hook after after the Control Plane for the Cluster is reachable for the first time.\n" +
+		Summary: "Cluster API Runtime will call this hook after the control plane is reachable for the first time",
+		Description: "Cluster API Runtime will call this hook after the control plane for the Cluster is reachable for the first time.\n" +
 			"\n" +
 			"Notes:\n" +
 			"- This hook will be called only for Clusters with a managed topology\n" +
@@ -231,8 +231,8 @@ func init() {
 
 	catalogBuilder.RegisterHook(AfterClusterUpgrade, &runtimecatalog.HookMeta{
 		Tags:    []string{"Lifecycle Hooks"},
-		Summary: "Cluster API Runtime will call this hook after Cluster is upgraded",
-		Description: "Cluster API Runtime will call this hook after the a Cluster has been upgraded to the version specified " +
+		Summary: "Cluster API Runtime will call this hook after a Cluster is upgraded",
+		Description: "Cluster API Runtime will call this hook after a Cluster has been upgraded to the version specified " +
 			"in spec.topology.version. An upgrade is completed when all control plane and MachineDeployment's Machines have been upgraded.\n" +
 			"\n" +
 			"Notes:\n" +