fix(api): correct grammar in CRD doc comments

api/formance.com/v1beta1/auth_types.go

@@ -40,16 +40,16 @@ type AuthSpec struct {
 	// Contains information about a delegated authentication server to use to delegate authentication
 	DelegatedOIDCServer *DelegatedOIDCServerConfiguration `json:"delegatedOIDCServer,omitempty"`
 	//+optional
-	// Allow to override the default signing key used to sign JWT tokens.
+	// Overrides the default signing key used to sign JWT tokens.
 	SigningKey string `json:"signingKey,omitempty"`
 	//+optional
-	// Allow to override the default signing key used to sign JWT tokens using a k8s secret
+	// Overrides the default signing key used to sign JWT tokens, using a k8s secret
 	SigningKeyFromSecret *v1.SecretKeySelector `json:"signingKeyFromSecret,omitempty"`
 	//+optional
-	// Allow to enable scopes usage on authentication.
+	// Enables scope checking during authentication.
 	//
-	// If not enabled, each service will check the authentication but will not restrict access following scopes.
-	// in this case, if authenticated, it is ok.
+	// If not enabled, each service will check the authentication but will not restrict access according to scopes.
+	// In that case, being authenticated is sufficient.
 	// +kubebuilder:default:=false
 	EnableScopes bool `json:"enableScopes"`
 }
@@ -61,11 +61,11 @@ type AuthStatus struct {
 	Clients []string `json:"clients"`
 }
 
-// Auth represent the authentication module of a stack.
+// Auth represents the authentication module of a stack.
 //
-// It is an OIDC compliant server.
+// It is an OIDC-compliant server.
 //
-// Creating it for a stack automatically add authentication on all supported modules.
+// Creating it for a stack automatically adds authentication to all supported modules.
 //
 // The auth service is basically a proxy to another OIDC compliant server.
 // +kubebuilder:object:root=true

api/formance.com/v1beta1/authclient_types.go

@@ -28,26 +28,26 @@ type AuthClientSpec struct {
 	// It must be used with oauth2 `client_id` parameter
 	ID string `json:"id" yaml:"id"`
 	// +optional
-	// Public indicate whether a client is confidential or not.
-	// Confidential clients are clients which the secret can be kept secret...
-	// As opposed to public clients which cannot have a secret (application single page for example)
+	// Public indicates whether the client is a public client.
+	// Confidential clients (the default) are clients whose secret can be kept secret.
+	// Public clients cannot hold a secret (a single-page application, for example)
 	// +kubebuilder:default:=false
 	Public bool `json:"public" yaml:"public"`
 	// +optional
 	// Description represents an optional description of the client
 	Description string `json:"description,omitempty" yaml:"description,omitempty"`
 	// +optional
-	// RedirectUris allow to list allowed redirect uris for the client
+	// RedirectUris lists the allowed redirect URIs for the client
 	RedirectUris []string `json:"redirectUris,omitempty" yaml:"redirectUris"`
 	// +optional
-	// RedirectUris allow to list allowed post logout redirect uris for the client
+	// PostLogoutRedirectUris lists the allowed post-logout redirect URIs for the client
 	PostLogoutRedirectUris []string `json:"postLogoutRedirectUris,omitempty" yaml:"postLogoutRedirectUris"`
 	// +optional
-	// Scopes allow to five some scope to the client
+	// Scopes lists the scopes granted to the client
 	Scopes []string `json:"scopes,omitempty" yaml:"scopes"`
 	// +optional
-	// Secret allow to configure a secret for the client.
-	// It is not required as some client could use some oauth2 flows which does not requires a client secret
+	// Secret configures a secret for the client.
+	// It is not required, since some clients use oauth2 flows that do not require a client secret
 	Secret string `json:"secret,omitempty"`
 
 	// +optional
@@ -86,7 +86,7 @@ type AuthClientStatus struct {
 //+kubebuilder:printcolumn:name="Ready",type=string,JSONPath=".status.ready",description="Is ready"
 //+kubebuilder:printcolumn:name="Info",type=string,JSONPath=".status.info",description="Info"
 
-// AuthClient allow to create OAuth2/OIDC clients on the auth server (see [Auth](#auth))
+// AuthClient creates OAuth2/OIDC clients on the auth server (see [Auth](#auth))
 type AuthClient struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`

api/formance.com/v1beta1/broker_types.go

@@ -24,7 +24,7 @@ type BrokerSpec struct {
 	StackDependency `json:",inline"`
 }
 
-// Mode defined how streams are created on the broker (mainly nats)
+// Mode defines how streams are created on the broker (mainly NATS)
 type Mode string
 
 const (
@@ -38,10 +38,10 @@ type BrokerStatus struct {
 	URI *URI `json:"uri,omitempty"`
 	//+optional
 	//+kubebuilder:validation:Enum:={OneStreamByService, OneStreamByStack}
-	// Mode indicating the configuration of the nats streams
-	// Two modes are defined :
-	// * ModeOneStreamByService: In this case, each service will have a dedicated stream created
-	// * ModeOneStreamByStack: In this case, a stream will be created for the stack and each service will use a specific subject inside this stream
+	// Mode indicating the configuration of the NATS streams
+	// Two modes are defined:
+	// - ModeOneStreamByService: In this case, each service will have a dedicated stream created
+	// - ModeOneStreamByStack: In this case, a stream will be created for the stack and each service will use a specific subject inside this stream
 	Mode Mode `json:"mode"`
 	// Streams list streams created when Mode == ModeOneStreamByService
 	//+optional

api/formance.com/v1beta1/connectivity_types.go

@@ -29,7 +29,7 @@ type ConnectivityStatus struct {
 	Status `json:",inline"`
 }
 
-// Connectivity is the module allowing to install a connectivity instance.
+// Connectivity declares the connectivity module on a stack. Creating it makes the operator deploy a connectivity instance.
 //
 // Connectivity ingests data from external sources (blockchains, payment
 // providers, ...) through a plugin system and writes double-entry

api/formance.com/v1beta1/database_types.go

@@ -23,8 +23,8 @@ import (
 type DatabaseSpec struct {
 	StackDependency `json:",inline"`
 	// Service is a discriminator for the created database.
-	// Actually, it will be the module name (ledger, payments...).
-	// Therefore, the created database will be named `<stack-name><service>`
+	// In practice, it is the module name (ledger, payments...).
+	// Therefore, the created database will be named `<stack-name>-<service>`
 	Service string `json:"service"`
 	// +kubebuilder:default:=false
 	Debug bool `json:"debug,omitempty"`
@@ -38,32 +38,33 @@ type DatabaseStatus struct {
 	// The generated database name
 	Database string `json:"database,omitempty"`
 	//+optional
-	// OutOfSync indicates than a settings changed the uri of the postgres server
-	// The Database object need to be removed to be recreated
+	// OutOfSync indicates that a setting changed the URI of the postgres server
+	// The Database object must be removed so that it can be recreated
 	OutOfSync bool `json:"outOfSync,omitempty"`
 }
 
-// Database represent a concrete database on a PostgreSQL server, it is created by modules requiring a database ([Ledger](#ledger) for example).
+// Database represents a concrete database on a PostgreSQL server. Modules that require a database create it ([Ledger](#ledger), for example).
 //
-// It uses the settings `postgres.<module-name>.uri` which must have the following uri format: `postgresql://[<username>@<password>]@<host>/<db-name>`
-// Additionally, the uri can define a query param `secret` indicating a k8s secret, than must be used to retrieve database credentials.
+// It uses the settings `postgres.<module-name>.uri` which must have the following URI format: `postgresql://[<username>:<password>@]<host>[:<port>]`.
+// The database name is not part of the setting: the operator derives it from the stack and the service.
+// Additionally, the URI can define a query param `secret` indicating a k8s secret that must be used to retrieve database credentials.
 // Credentials in the secret are expected to be URL-encoded by default. Set `secretCredentialsEncoding=raw` to let the operator encode them.
 //
 // On creation, the reconciler behind the Database object will create the database on the postgresql server using a k8s job.
-// On Deletion, by default, the reconciler will let the database untouched.
+// On Deletion, by default, the reconciler leaves the database untouched.
 // You can allow the reconciler to drop the database on the server by using the [Settings](#settings) `clear-database` with the value `true`.
 // If you use that setting, the reconciler will use another job to drop the database.
-// Be careful, no backup are performed!
+// Be careful: no backup is performed!
 //
 // Database resource honors `aws.service-account` setting, so, you can create databases on an AWS server if you need.
 // See [AWS accounts](#aws-account)
 //
-// Once a database is fully configured, it retains the postgres uri used.
-// If the setting indicating the server uri changed, the Database object will set the field `.status.outOfSync` to true
+// Once a database is fully configured, it retains the postgres URI used.
+// If the setting that specifies the server URI changes, the Database object will set the field `.status.outOfSync` to true
 // and will not change anything.
 //
 // Therefore, to switch to a new server, you must change the setting value, then drop the Database object.
-// It will be recreated with correct uri.
+// It will be recreated with the correct URI.
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:scope=Cluster

api/formance.com/v1beta1/gateway_types.go

@@ -28,15 +28,15 @@ type GatewayIngressTLS struct {
 // GatewayIngress represents the ingress configuration for the gateway.
 type GatewayIngress struct {
 	// Indicates the hostname on which the stack will be served.
-	// Example : `formance.example.com`
+	// Example: `stack.example.com`
 	//+required
 	Host string `json:"host"`
 	// Additional hosts for the ingress. Combined with Host.
 	//+optional
 	Hosts []string `json:"hosts,omitempty"`
-	// Indicate the scheme.
+	// Indicates the scheme.
 	//
-	// Actually, It should be `https` unless you know what you are doing.
+	// It should be `https` unless you know what you are doing.
 	// +kubebuilder:default:="https"
 	Scheme string `json:"scheme"`
 
@@ -46,7 +46,7 @@ type GatewayIngress struct {
 
 	// Custom annotations to add on the ingress
 	Annotations map[string]string `json:"annotations,omitempty"`
-	// Allow to customize the tls part of the ingress
+	// Customizes the TLS part of the ingress
 	//+optional
 	TLS *GatewayIngressTLS `json:"tls,omitempty"`
 }
@@ -77,7 +77,7 @@ type GatewaySpec struct {
 	StackDependency  `json:",inline"`
 	ModuleProperties `json:",inline"`
 	//+optional
-	// Allow to customize the generated ingress
+	// Customizes the generated ingress
 	Ingress *GatewayIngress `json:"ingress,omitempty"`
 }
 

api/formance.com/v1beta1/groupversion_info.go

@@ -16,11 +16,11 @@ limitations under the License.
 
 // Package v1beta1 contains API Schema definitions for the formance v1beta1 API group.
 //
-// It allow to configure a Formance stack.
+// These definitions let you configure a Formance stack.
 //
 // A stack is composed of a [Stack](#stack) resource and some [modules](#modules).
 //
-// Each module can create multiple resources following its needs. See [Other resources](#other-resources).
+// Each module can create multiple resources as needed. See [Other resources](#other-resources).
 //
 // Various parts of the stack can be configured either using the CRD properties or using some [Settings](#settings).
 //

api/formance.com/v1beta1/ledger_types.go

@@ -33,7 +33,7 @@ type LedgerStatus struct {
 	Status `json:",inline"`
 }
 
-// Ledger is the module allowing to install a ledger instance.
+// Ledger declares the ledger module on a stack. Creating it makes the operator deploy a ledger instance.
 //
 // The ledger is a stateful application that manages financial transactions
 // and maintains an immutable audit trail.

api/formance.com/v1beta1/resourcereference_types.go

@@ -34,19 +34,18 @@ type ResourceReferenceStatus struct {
 	Hash string `json:"hash,omitempty"`
 }
 
-// ResourceReference is a special resources used to refer to externally created resources.
+// ResourceReference gives a stack access to a Kubernetes object created outside the operator — for example a secret
+// holding the credentials of an existing Postgres server, or a service account granting access to AWS.
 //
-// It includes k8s service accounts and secrets.
+// The indirection is needed because the operator gives each stack its own namespace, and a stack cannot read secrets
+// or service accounts that live in another namespace.
 //
-// Why? Because the operator create a namespace by stack, so, a stack does not have access to secrets and service
-// accounts created externally.
-//
-// A ResourceReference is created by other resource who need to use a specific secret or service account.
-// For example, if you want to use a secret for your database connection (see [Database](#database), you will
+// A ResourceReference is created by another resource that needs a specific secret or service account.
+// For example, if you want to use a secret for your database connection (see [Database](#database)), you will
 // create a setting indicating a secret name. You will need to create this secret yourself, and you will put this
 // secret inside the namespace you want (`default` maybe).
 //
-// The Database reconciler will create a ResourceReference looking like that :
+// The Database reconciler creates a ResourceReference with the following shape:
 // ```
 // apiVersion: formance.com/v1beta1
 // kind: ResourceReference
@@ -75,10 +74,10 @@ type ResourceReferenceStatus struct {
 //	...
 //
 // ```
-// This reconciler behind this ResourceReference will search, in all namespaces, for a secret named "postgres".
+// The ResourceReference reconciler then searches every namespace for a secret named `postgres`.
 // The secret must have a label `formance.com/stack` with the value matching either a specific stack or `any` to target any stack.
 //
-// Once the reconciler has found the secret, it will copy it inside the stack namespace, allowing the ResourceReconciler owner to use it.
+// Once the reconciler has found the secret, it copies it into the stack namespace, so the owner of the ResourceReference can use it.
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:scope=Cluster

api/formance.com/v1beta1/settings_types.go

@@ -26,15 +26,15 @@ type SettingsSpec struct {
 	Stacks []string `json:"stacks,omitempty"`
 	// The setting Key. See the documentation of each module or [global settings](#global-settings) to discover them.
 	Key string `json:"key"`
-	// The value. It must have a specific format following the Key.
+	// Value is the setting value. Its required format depends on the Key.
 	Value string `json:"value"`
 }
 
 // Settings represents a configurable piece of the stacks.
 //
-// The purpose of this resource is to be able to configure some common settings between a set of stacks.
+// The purpose of this resource is to configure settings shared across a set of stacks.
 //
-// Example :
+// Example:
 // ```yaml
 // apiVersion: formance.com/v1beta1
 // kind: Settings
@@ -51,13 +51,13 @@ type SettingsSpec struct {
 //
 // ```
 //
-// This example create a setting named `postgres-uri` targeting the stack named `stack0` and the service `ledger` (see the key `postgres.ledger.uri`).
+// This example creates a setting named `postgres-uri` targeting the stack named `stack0` and the service `ledger` (see the key `postgres.ledger.uri`).
 //
-// Therefore, a [Database](#database) created for the stack `stack0` and the service named 'ledger' will use the uri `postgresql://postgresql.formance.svc.cluster.local:5432`.
+// Therefore, a [Database](#database) created for the stack `stack0` and the service named 'ledger' will use the URI `postgresql://postgresql.formance.svc.cluster.local:5432`.
 //
-// Settings allow to use wildcards in keys and in stacks list.
+// Settings supports wildcards in keys and in the stacks list.
 //
-// For example, if you want to use the same database server for all the modules of a specific stack, you can write :
+// For example, if you want to use the same database server for all the modules of a specific stack, you can write:
 // ```yaml
 // apiVersion: formance.com/v1beta1
 // kind: Settings
@@ -74,7 +74,7 @@ type SettingsSpec struct {
 //
 // ```
 //
-// Also, we could use that setting for all of our stacks using :
+// Also, we could use that setting for all of our stacks using:
 // ```yaml
 // apiVersion: formance.com/v1beta1
 // kind: Settings
@@ -91,7 +91,7 @@ type SettingsSpec struct {
 //
 // ```
 //
-// Some settings are really global, while some are used by specific module.
+// Some settings are truly global, while others are used by a specific module.
 //
 // Refer to the documentation of each module and resource to discover available Settings.
 //
@@ -100,7 +100,7 @@ type SettingsSpec struct {
 //
 // A stack can use an AWS account for authentication.
 //
-// It can be used to connect to any AWS service we could use.
+// It can be used to connect to any AWS service.
 //
 // It includes RDS, OpenSearch and MSK. To do so, you can create the following setting:
 // ```yaml
@@ -118,11 +118,11 @@ type SettingsSpec struct {
 //	value: aws-access
 //
 // ```
-// This setting instruct the operator than there is somewhere on the cluster a service account named `aws-access`.
+// This setting tells the operator that a service account named `aws-access` exists somewhere on the cluster.
 //
 // So, each time a service has the capability to use AWS, the operator will use this service account.
 //
-// The service account could look like that :
+// The service account could look like this:
 // ```yaml
 // apiVersion: v1
 // kind: ServiceAccount
@@ -135,14 +135,14 @@ type SettingsSpec struct {
 //	name: aws-access
 //
 // ```
-// You can note two things :
-//  1. We have an annotation indicating the role arn used to connect to AWS. Refer to the AWS documentation to create this role
+// You can note two things:
+//  1. We have an annotation indicating the role ARN used to connect to AWS. Refer to the AWS documentation to create this role
 //  2. We have a label `formance.com/stack=any` indicating we are targeting all stacks.
 //     Refer to the documentation of [ResourceReference](#resourcereference) for further information.
 //
 // ###### JSON logging
 //
-// You can use the setting `logging.json` with the value `true` to configure elligible service to log as json.
+// You can use the setting `logging.json` with the value `true` to configure eligible services to log as JSON.
 // Example:
 // ```yaml
 // apiVersion: formance.com/v1beta1

api/formance.com/v1beta1/shared.go

@@ -30,12 +30,12 @@ type VersionedEventPublisher interface {
 
 type DevProperties struct {
 	// +optional
-	// Allow to enable debug mode on the module
+	// Enables debug mode on the module
 	// +kubebuilder:default:=false
 	Debug bool `json:"debug"`
 	// +optional
-	// Allow to enable dev mode on the module
-	// Dev mode is used to allow some application to do custom setup in development mode (allow insecure certificates for example)
+	// Enables dev mode on the module
+	// Dev mode lets an application do custom setup in development mode (allowing insecure certificates, for example)
 	// +kubebuilder:default:=false
 	Dev bool `json:"dev"`
 }
@@ -236,7 +236,7 @@ type Status struct {
 	// Ready indicates if the resource is seen as completely reconciled
 	Ready bool `json:"ready"`
 	//+optional
-	// Info can contain any additional like reconciliation errors
+	// Info can contain any additional detail, such as reconciliation errors
 	Info string `json:"info,omitempty"`
 	//+optional
 	Conditions Conditions `json:"conditions,omitempty"`
@@ -269,7 +269,7 @@ type Module interface {
 type ModuleProperties struct {
 	DevProperties `json:",inline"`
 	//+optional
-	// Version allow to override global version defined at stack level for a specific module
+	// Version overrides, for a specific module, the global version defined at stack level
 	Version string `json:"version,omitempty"`
 }