From 3f9bbf1d4ae54c6f655767268b30882af123f466 Mon Sep 17 00:00:00 2001 From: Brian Flad Date: Tue, 2 Aug 2022 12:27:51 -0400 Subject: [PATCH] all: Go package documentation updates post datasource, provider, and resource package migration Reference: https://github.com/hashicorp/terraform-plugin-framework/pull/432 --- datasource/data_source.go | 10 ++++++++-- datasource/doc.go | 15 +++++++++++++++ provider/doc.go | 19 +++++++++++++++++++ provider/provider.go | 7 +++++++ providerserver/doc.go | 10 ++++++++++ resource/doc.go | 19 +++++++++++++++++++ resource/resource.go | 18 +++++++++++++----- 7 files changed, 91 insertions(+), 7 deletions(-) diff --git a/datasource/data_source.go b/datasource/data_source.go index 7101957bc..37e50fc3a 100644 --- a/datasource/data_source.go +++ b/datasource/data_source.go @@ -2,8 +2,14 @@ package datasource import "context" -// DataSource represents a data source instance. This is the core interface that -// all data sources must implement. +// DataSource represents an instance of a data source type. This is the core +// interface that all data sources must implement. +// +// Data sources can optionally implement these additional concepts: +// +// - Validation: Schema-based via tfsdk.Attribute or entire configuration +// via DataSourceWithConfigValidators or DataSourceWithValidateConfig. +// type DataSource interface { // Read is called when the provider must read data source values in // order to update state. Config values should be read from the diff --git a/datasource/doc.go b/datasource/doc.go index 9276adf4e..fd7a4fc82 100644 --- a/datasource/doc.go +++ b/datasource/doc.go @@ -1,3 +1,18 @@ // Package datasource contains all interfaces, request types, and response // types for a data source implementation. +// +// In Terraform, a data source is a concept which enables provider developers +// to offer practitioners a read-only source of information, which is saved +// into the Terraform state and can be referenced by other parts of a +// configuration. Data sources are defined by a data source type/name, such as +// "example_thing", a schema representing the structure and data types of +// configuration and state, and read logic. +// +// The main starting point for implementations in this package is the +// DataSource type which represents an instance of a data source type that has +// its own configuration, read logic, and state. A DataSource is instantiated +// from a provider.DataSourceType type NewDataSource method, which also defines +// the data source schema. The provider.DataSourceType types are referenced by +// a provider.Provider type GetDataSources method, which enables the data +// source for practitioner and testing usage. package datasource diff --git a/provider/doc.go b/provider/doc.go index e39c5b235..954f7afc7 100644 --- a/provider/doc.go +++ b/provider/doc.go @@ -1,3 +1,22 @@ // Package provider contains all interfaces, request types, and response // types for a provider implementation. +// +// In Terraform, a provider is a concept which enables provider developers +// to offer practitioners data sources and managed resources. Those concepts +// are described in more detail in their respective datasource and resource +// packages. +// +// Providers generally store any infrastructure clients or shared data that is +// applicable across data sources and managed resources. Providers are +// generally configured early in Terraform operations, such as plan and apply, +// before data source and managed resource logic is called. However, this early +// provider configuration is not guaranteed in the case there are unknown +// Terraform configuration values, so additional logic checks may be required +// throughout an implementation to handle this case. Providers may contain a +// schema representing the structure and data types of Terraform-based +// configuration. +// +// The main starting point for implementations in this package is the +// Provider type which represents an instance of a provider that has +// its own configuration. package provider diff --git a/provider/provider.go b/provider/provider.go index d330539a2..35b4b0520 100644 --- a/provider/provider.go +++ b/provider/provider.go @@ -8,6 +8,13 @@ import ( ) // Provider is the core interface that all Terraform providers must implement. +// +// Providers can optionally implement these additional concepts: +// +// - Validation: Schema-based via tfsdk.Attribute or entire configuration +// via ProviderWithConfigValidators or ProviderWithValidateConfig. +// - Meta Schema: ProviderWithMetaSchema +// type Provider interface { // GetSchema returns the schema for this provider's configuration. If // this provider has no configuration, return an empty schema.Schema. diff --git a/providerserver/doc.go b/providerserver/doc.go index f26c986a9..ebea40f15 100644 --- a/providerserver/doc.go +++ b/providerserver/doc.go @@ -1,4 +1,14 @@ // Package providerserver implements functionality for serving a provider, // such as directly starting a server in a production binary and conversion // functions for testing. +// +// For production usage, call the Serve function from binary startup, such as +// from the provider codebase main package. If multiplexing the provider server +// via terraform-plugin-mux functionality, use the NewProtocol* functions and +// call the Serve function from that Go module. For testing usage, call the +// NewProtocol* functions. +// +// All functionality in this package requires the provider.Provider type, which +// contains the provider implementation including all managed resources and +// data sources. package providerserver diff --git a/resource/doc.go b/resource/doc.go index e76624bf2..2aecf47c6 100644 --- a/resource/doc.go +++ b/resource/doc.go @@ -1,3 +1,22 @@ // Package resource contains all interfaces, request types, and response types // for a managed resource implementation. +// +// In Terraform, a managed resource is a concept which enables provider +// developers to offer practitioners full lifecycle management (create, read, +// update, and delete) of a infrastructure component. Managed resources can +// also stand in for one-time infrastructure operations that require tracking, +// by implementing create logic, while omitting update and delete logic. +// +// Resources are saved into the Terraform state and can be referenced by other +// parts of a configuration. Resources are defined by a resource type/name, +// such as "example_thing", a schema representing the structure and data types +// of configuration, plan, and state, and lifecycle logic. +// +// The main starting point for implementations in this package is the +// Resource type which represents an instance of a resource type that has +// its own configuration, plan, state, and lifecycle logic. A Resource is +// instantiated from a provider.ResourceType type NewResource method, which +// also defines the resource schema. The provider.ResourceType types are +// referenced by a provider.Provider type GetResources method, which enables +// the resource for practitioner and testing usage. package resource diff --git a/resource/resource.go b/resource/resource.go index 571510db9..38e1578ec 100644 --- a/resource/resource.go +++ b/resource/resource.go @@ -4,12 +4,20 @@ import ( "context" ) -// Resource represents a resource instance. This is the core interface that all -// resources must implement. +// Resource represents an instance of a managed resource type. This is the core +// interface that all resources must implement. // -// It is also conventional for resources to implement the -// ResourceWithImportState interface, which enables practitioners to import -// existing infrastructure into Terraform. +// Resources can optionally implement these additional concepts: +// +// - Import: ResourceWithImportState +// - Validation: Schema-based via tfsdk.Attribute or entire configuration +// via ResourceWithConfigValidators or ResourceWithValidateConfig. +// - Plan Modification: Schema-based via tfsdk.Attribute or entire plan +// via ResourceWithModifyPlan. +// - State Upgrades: ResourceWithUpgradeState +// +// Although not required, it is conventional for resources to implement the +// ResourceWithImportState interface. type Resource interface { // Create is called when the provider must create a new resource. Config // and planned state values should be read from the