Updates API godocs for improved markdown rendering (envoyproxy#1010)

Updates API godocs for improved html rendering

Signed-off-by: danehans <daneyonhansen@gmail.com>
(cherry picked from commit b43574a)
Signed-off-by: bitliu <bitliu@tencent.com>

api/config/v1alpha1/doc.go

@@ -3,7 +3,7 @@
 // The full text of the Apache license is available in the LICENSE file at
 // the root of the repo.
 
-// Package v1alpha1 contains API Schema definitions for the config.gateway.envoyproxy.io
+// Package v1alpha1 contains API schema definitions for the config.gateway.envoyproxy.io
 // API group.
 //
 // +kubebuilder:object:generate=true

api/config/v1alpha1/envoygateway_types.go

@@ -18,11 +18,11 @@ const (
 
 //+kubebuilder:object:root=true
 
-// EnvoyGateway is the Schema for the envoygateways API.
+// EnvoyGateway is the schema for the envoygateways API.
 type EnvoyGateway struct {
 	metav1.TypeMeta `json:",inline"`
 
-	// EnvoyGatewaySpec defines the desired state of Envoy Gateway.
+	// EnvoyGatewaySpec defines the desired state of EnvoyGateway.
 	EnvoyGatewaySpec `json:",inline"`
 }
 
@@ -45,7 +45,7 @@ type EnvoyGatewaySpec struct {
 	// deployed by Envoy Gateway required to implement the Global Rate limiting
 	// functionality. The specific rate limit service used here is the reference
 	// implementation in Envoy. For more details visit https://github.com/envoyproxy/ratelimit.
-	// This configuration will not be needed to enable Local Rate limiitng.
+	// This configuration is unneeded for "Local" rate limiting.
 	//
 	// +optional
 	RateLimit *RateLimit `json:"rateLimit,omitempty"`
@@ -56,8 +56,7 @@ type Gateway struct {
 	// ControllerName defines the name of the Gateway API controller. If unspecified,
 	// defaults to "gateway.envoyproxy.io/gatewayclass-controller". See the following
 	// for additional details:
-	//
-	// https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass
+	//   https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass
 	//
 	// +optional
 	ControllerName string `json:"controllerName,omitempty"`
@@ -66,20 +65,20 @@ type Gateway struct {
 // Provider defines the desired configuration of a provider.
 // +union
 type Provider struct {
-	// Type is the type of provider to use. Supported types are:
-	//
-	//   * Kubernetes: A provider that provides runtime configuration via the Kubernetes API.
+	// Type is the type of provider to use. Supported types are "Kubernetes".
 	//
 	// +unionDiscriminator
 	Type ProviderType `json:"type"`
+
 	// Kubernetes defines the configuration of the Kubernetes provider. Kubernetes
 	// provides runtime configuration via the Kubernetes API.
 	//
 	// +optional
 	Kubernetes *KubernetesProvider `json:"kubernetes,omitempty"`
 
 	// File defines the configuration of the File provider. File provides runtime
-	// configuration defined by one or more files.
+	// configuration defined by one or more files. This type is not implemented
+	// until https://github.com/envoyproxy/gateway/issues/1001 is fixed.
 	//
 	// +optional
 	File *FileProvider `json:"file,omitempty"`

api/config/v1alpha1/envoyproxy_types.go

@@ -17,12 +17,14 @@ const (
 //+kubebuilder:object:root=true
 //+kubebuilder:subresource:status
 
-// EnvoyProxy is the Schema for the envoyproxies API
+// EnvoyProxy is the schema for the envoyproxies API.
 type EnvoyProxy struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   EnvoyProxySpec   `json:"spec,omitempty"`
+	// EnvoyProxySpec defines the desired state of EnvoyProxy.
+	Spec EnvoyProxySpec `json:"spec,omitempty"`
+	// EnvoyProxyStatus defines the actual state of EnvoyProxy.
 	Status EnvoyProxyStatus `json:"status,omitempty"`
 }
 
@@ -36,7 +38,8 @@ type EnvoyProxySpec struct {
 	Provider *ResourceProvider `json:"provider,omitempty"`
 
 	// Logging defines logging parameters for managed proxies. If unspecified,
-	// default settings apply.
+	// default settings apply. This type is not implemented until
+	// https://github.com/envoyproxy/gateway/issues/280 is fixed.
 	//
 	// +kubebuilder:default={level: {system: info}}
 	Logging ProxyLogging `json:"logging,omitempty"`
@@ -47,10 +50,7 @@ type EnvoyProxySpec struct {
 type ResourceProvider struct {
 	// Type is the type of resource provider to use. A resource provider provides
 	// infrastructure resources for running the data plane, e.g. Envoy proxy, and
-	// optional auxiliary control planes. Supported types are:
-	//
-	//   * Kubernetes: Provides infrastructure resources for running the data plane,
-	//                 e.g. Envoy proxy.
+	// optional auxiliary control planes. Supported types are "Kubernetes".
 	//
 	// +unionDiscriminator
 	Type ProviderType `json:"type"`
@@ -74,7 +74,8 @@ type KubernetesResourceProvider struct {
 	EnvoyDeployment *KubernetesDeploymentSpec `json:"envoyDeployment,omitempty"`
 }
 
-// ProxyLogging defines logging parameters for managed proxies.
+// ProxyLogging defines logging parameters for managed proxies. This type is not
+// implemented until https://github.com/envoyproxy/gateway/issues/280 is fixed.
 type ProxyLogging struct {
 	// Level is a map of logging level per component, where the component is the key
 	// and the log level is the value. If unspecified, defaults to "System: Info".
@@ -84,7 +85,8 @@ type ProxyLogging struct {
 }
 
 // LogComponent defines a component that supports a configured logging level.
-//
+// This type is not implemented until https://github.com/envoyproxy/gateway/issues/280
+// is fixed.
 // +kubebuilder:validation:Enum=system;upstream;http;connection;admin;client;filter;main;router;runtime
 type LogComponent string
 
@@ -121,8 +123,8 @@ const (
 	LogComponentRuntime LogComponent = "runtime"
 )
 
-// LogLevel defines a log level for system logs.
-//
+// LogLevel defines a log level for system logs. This type is not implemented until
+// https://github.com/envoyproxy/gateway/issues/280 is fixed.
 // +kubebuilder:validation:Enum=debug;info;error
 type LogLevel string
 
@@ -137,7 +139,8 @@ const (
 	LogLevelError LogLevel = "error"
 )
 
-// EnvoyProxyStatus defines the observed state of EnvoyProxy
+// EnvoyProxyStatus defines the observed state of EnvoyProxy. This type is not implemented
+// until https://github.com/envoyproxy/gateway/issues/1007 is fixed.
 type EnvoyProxyStatus struct {
 	// INSERT ADDITIONAL STATUS FIELDS - define observed state of cluster.
 	// Important: Run "make" to regenerate code after modifying this file.

api/config/v1alpha1/shared_types.go

@@ -19,7 +19,8 @@ const (
 	// ProviderTypeKubernetes defines the "Kubernetes" provider.
 	ProviderTypeKubernetes ProviderType = "Kubernetes"
 
-	// ProviderTypeFile defines the "File" provider.
+	// ProviderTypeFile defines the "File" provider. This type is not implemented
+	// until https://github.com/envoyproxy/gateway/issues/1001 is fixed.
 	ProviderTypeFile ProviderType = "File"
 )
 

api/v1alpha1/authenticationfilter_types.go

@@ -29,18 +29,16 @@ type AuthenticationFilter struct {
 // AuthenticationFilterSpec defines the desired state of the AuthenticationFilter type.
 // +union
 type AuthenticationFilterSpec struct {
-	// Type defines the type of authentication provider to use. Supported provider types are:
-	//
-	//   * JWT: A provider that uses JSON Web Token (JWT) for authenticating requests.
+	// Type defines the type of authentication provider to use. Supported provider types
+	// are "JWT".
 	//
 	// +unionDiscriminator
 	Type AuthenticationFilterType `json:"type"`
 
 	// JWT defines the JSON Web Token (JWT) authentication provider type. When multiple
 	// jwtProviders are specified, the JWT is considered valid if any of the providers
-	// successfully validate the JWT. For additional details, see:
-	//
-	//   https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter.html
+	// successfully validate the JWT. For additional details, see
+	// https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter.html.
 	//
 	// +kubebuilder:validation:MaxItems=4
 	// +optional
@@ -52,7 +50,8 @@ type AuthenticationFilterSpec struct {
 type AuthenticationFilterType string
 
 const (
-	// JwtAuthenticationFilterProviderType is the JWT authentication provider type.
+	// JwtAuthenticationFilterProviderType is a provider that uses JSON Web Token (JWT)
+	// for authenticating requests..
 	JwtAuthenticationFilterProviderType AuthenticationFilterType = "JWT"
 )
 
@@ -67,33 +66,17 @@ type JwtAuthenticationFilterProvider struct {
 	Name string `json:"name"`
 
 	// Issuer is the principal that issued the JWT and takes the form of a URL or email address.
-	// For additional details, see:
-	//
-	//   URL format: https://tools.ietf.org/html/rfc7519#section-4.1.1
-	//   Email format: https://rfc-editor.org/rfc/rfc5322.html
-	//
-	// URL Example:
-	//  issuer: https://auth.example.com
-	//
-	// Email Example:
-	//  issuer: jdoe@example.com
-	//
-	// If not provided, the JWT issuer is not checked.
+	// For additional details, see https://tools.ietf.org/html/rfc7519#section-4.1.1 for
+	// URL format and https://rfc-editor.org/rfc/rfc5322.html for email format. If not provided,
+	// the JWT issuer is not checked.
 	//
 	// +kubebuilder:validation:MaxLength=253
 	// +optional
 	Issuer string `json:"issuer,omitempty"`
 
-	// Audiences is a list of JWT audiences allowed to access. For additional details, see:
-	//
-	//   https://tools.ietf.org/html/rfc7519#section-4.1.3
-	//
-	// Example:
-	//   audiences:
-	//   - foo.apps.example.com
-	//     bar.apps.example.com
-	//
-	// If not provided, JWT audiences are not checked.
+	// Audiences is a list of JWT audiences allowed access. For additional details, see
+	// https://tools.ietf.org/html/rfc7519#section-4.1.3. If not provided, JWT audiences
+	// are not checked.
 	//
 	// +kubebuilder:validation:MaxItems=8
 	// +optional
@@ -112,9 +95,6 @@ type RemoteJWKS struct {
 	// URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to
 	// validate the server certificate.
 	//
-	// Example:
-	//  uri: https://www.foo.com/oauth2/v1/certs
-	//
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=253
 	URI string `json:"uri"`

api/v1alpha1/doc.go

@@ -3,7 +3,7 @@
 // The full text of the Apache license is available in the LICENSE file at
 // the root of the repo.
 
-// Package v1alpha1 contains API Schema definitions for the gateway.envoyproxy.io API group.
+// Package v1alpha1 contains API schema definitions for the gateway.envoyproxy.io API group.
 //
 // +kubebuilder:object:generate=true
 // +groupName=gateway.envoyproxy.io

api/v1alpha1/ratelimitfilter_types.go

@@ -30,13 +30,11 @@ type RateLimitFilter struct {
 // +union
 type RateLimitFilterSpec struct {
 	// Type decides the scope for the RateLimits.
-	// Valid RateLimitType values are:
-	//
-	// * "Global" - In this mode, the rate limits are applied across all Envoy proxy instances.
+	// Valid RateLimitType values are "Global".
 	//
 	// +unionDiscriminator
 	Type RateLimitType `json:"type"`
-	// Global rate limit configuration.
+	// Global defines global rate limit configuration.
 	//
 	// +optional
 	Global *GlobalRateLimit `json:"global,omitempty"`
@@ -51,7 +49,7 @@ const (
 	GlobalRateLimitType RateLimitType = "Global"
 )
 
-// GlobalRateLimit defines the global rate limit configuration.
+// GlobalRateLimit defines global rate limit configuration.
 type GlobalRateLimit struct {
 	// Rules are a list of RateLimit selectors and limits.
 	// Each rule and its associated limit is applied
@@ -116,29 +114,33 @@ type HeaderMatch struct {
 
 	// Value within the HTTP header. Due to the
 	// case-insensitivity of header names, "foo" and "Foo" are considered equivalent.
-	// Do not set this field when Type="Distinct", implying matching on any/all unique values within the header.
+	// Do not set this field when Type="Distinct", implying matching on any/all unique
+	// values within the header.
+	//
 	// +optional
 	// +kubebuilder:validation:MaxLength=1024
 	Value *string `json:"value,omitempty"`
 }
 
-// HeaderMatchType specifies the semantics of how HTTP header values should be
-// compared. Valid HeaderMatchType values are:
-//
-//   - "Exact": Use this type to match the exact value of the Value field against the value of the specified HTTP Header.
-//   - "RegularExpression": Use this type to match a regular expression against the value of the specified HTTP Header.
-//     The regex string must adhere to the syntax documented in https://github.com/google/re2/wiki/Syntax.
-//   - "Distinct": Use this type to match any and all possible unique values encountered in the specified HTTP Header.
-//     Note that each unique value will receive its own rate limit bucket.
+// HeaderMatchType specifies the semantics of how HTTP header values should be compared.
+// Valid HeaderMatchType values are "Exact", "RegularExpression", and "Distinct".
 //
 // +kubebuilder:validation:Enum=Exact;RegularExpression;Distinct
 type HeaderMatchType string
 
 // HeaderMatchType constants.
 const (
-	HeaderMatchExact             HeaderMatchType = "Exact"
+	// HeaderMatchExact matches the exact value of the Value field against the value of
+	// the specified HTTP Header.
+	HeaderMatchExact HeaderMatchType = "Exact"
+	// HeaderMatchRegularExpression matches a regular expression against the value of the
+	// specified HTTP Header. The regex string must adhere to the syntax documented in
+	// https://github.com/google/re2/wiki/Syntax.
 	HeaderMatchRegularExpression HeaderMatchType = "RegularExpression"
-	HeaderMatchDistinct          HeaderMatchType = "Distinct"
+	// HeaderMatchDistinct matches any and all possible unique values encountered in the
+	// specified HTTP Header. Note that each unique value will receive its own rate limit
+	// bucket.
+	HeaderMatchDistinct HeaderMatchType = "Distinct"
 )
 
 // RateLimitValue defines the limits for rate limiting.