all: Go package documentation updates post datasource, provider, and resource package migration (#436)

Reference: #432

Author: bflad

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

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

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

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.

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

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

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