Document the tf5server package.

Also, rename it to tf5server, which is better than tfprotov5server.

Author: Paddy Carver

tfprotov5/server/doc.go

@@ -0,0 +1,6 @@
+// Package tf5server implementations a server implementation for running
+// tfprotov5.ProviderServers as gRPC servers.
+//
+// Providers will likely be calling tf5server.Serve from their main function to
+// start the server so Terraform can connect to it.
+package tf5server

tfprotov5/server/plugin.go

@@ -1,4 +1,4 @@
-package tfprotov5server
+package tf5server
 
 import (
 	"context"
@@ -11,22 +11,34 @@ import (
 	"google.golang.org/grpc"
 )
 
+// GRPCProviderPlugin is an implementation of the
+// github.com/hashicorp/go-plugin#Plugin and
+// github.com/hashicorp/go-plugin#GRPCPlugin interfaces, indicating how to
+// serve tfprotov5.ProviderServers as gRPC plugins for go-plugin.
 type GRPCProviderPlugin struct {
 	GRPCProvider func() tfprotov5.ProviderServer
 }
 
+// Server always returns an error; we're only implementing the GRPCPlugin
+// interface, not the Plugin interface.
 func (p *GRPCProviderPlugin) Server(*plugin.MuxBroker) (interface{}, error) {
 	return nil, errors.New("terraform-plugin-go only implements gRPC servers")
 }
 
+// Client always returns an error; we're only implementing the GRPCPlugin
+// interface, not the Plugin interface.
 func (p *GRPCProviderPlugin) Client(*plugin.MuxBroker, *rpc.Client) (interface{}, error) {
 	return nil, errors.New("terraform-plugin-go only implements gRPC servers")
 }
 
+// GRPCClient always returns an error; we're only implementing the server half
+// of the interface.
 func (p *GRPCProviderPlugin) GRPCClient(context.Context, *plugin.GRPCBroker, *grpc.ClientConn) (interface{}, error) {
 	return nil, errors.New("terraform-plugin-go only implements gRPC servers")
 }
 
+// GRPCServer registers the gRPC provider server with the gRPC server that
+// go-plugin is standing up.
 func (p *GRPCProviderPlugin) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error {
 	tfplugin5.RegisterProviderServer(s, New(p.GRPCProvider()))
 	return nil

tfprotov5/server/server.go

@@ -1,4 +1,4 @@
-package tfprotov5server
+package tf5server
 
 import (
 	"context"
@@ -11,10 +11,16 @@ import (
 	"github.com/hashicorp/terraform-plugin-go/tfprotov5/internal/toproto"
 )
 
+// ServeOpt is an interface for defining options that can be passed to the
+// Serve function. Each implementation modifies the ServeConfig being
+// generated. A slice of ServeOpts then, cumulatively applied, render a full
+// ServeConfig.
 type ServeOpt interface {
 	ApplyServeOpt(*ServeConfig) error
 }
 
+// ServeConfig contains the configured options for how a provider should be
+// served.
 type ServeConfig struct {
 	logger       hclog.Logger
 	debugCtx     context.Context
@@ -28,6 +34,8 @@ func (s serveConfigFunc) ApplyServeOpt(in *ServeConfig) error {
 	return s(in)
 }
 
+// WithDebug returns a ServeOpt that will set the server into debug mode, using
+// the passed options to populate the go-plugin ServeTestConfig.
 func WithDebug(ctx context.Context, config chan *plugin.ReattachConfig, closeCh chan struct{}) ServeOpt {
 	return serveConfigFunc(func(in *ServeConfig) error {
 		in.debugCtx = ctx
@@ -37,13 +45,24 @@ func WithDebug(ctx context.Context, config chan *plugin.ReattachConfig, closeCh
 	})
 }
 
+// WithGoPluginLogger returns a ServeOpt that will set the logger that
+// go-plugin should use to log messages.
 func WithGoPluginLogger(logger hclog.Logger) ServeOpt {
 	return serveConfigFunc(func(in *ServeConfig) error {
 		in.logger = logger
 		return nil
 	})
 }
 
+// Serve starts a tfprotov5.ProviderServer serving, ready for Terraform to
+// connect to it. The name passed in should be the fully qualified name that
+// users will enter in the source field of the required_providers block, like
+// "registry.terraform.io/hashicorp/time".
+//
+// Zero or more options to configure the server may also be passed. The default
+// invocation is sufficient, but if the provider wants to run in debug mode or
+// modify the logger that go-plugin is using, ServeOpts can be specified to
+// support that.
 func Serve(name string, serverFactory func() tfprotov5.ProviderServer, opts ...ServeOpt) error {
 	var conf ServeConfig
 	for _, opt := range opts {
@@ -84,6 +103,8 @@ type server struct {
 	tfplugin5.UnimplementedProviderServer
 }
 
+// New converts a tfprotov5.ProviderServer into a server capable of handling
+// Terraform protocol requests and issuing responses using the gRPC types.
 func New(serve tfprotov5.ProviderServer) tfplugin5.ProviderServer {
 	return server{
 		downstream: serve,