From ea767aa7add3e14b7d292efead3ef23d25cd49e1 Mon Sep 17 00:00:00 2001
From: Sarah French <15078782+SarahFrench@users.noreply.github.com>
Date: Tue, 8 Apr 2025 15:24:19 -0500
Subject: [PATCH] Add comments about use of ResourceStores with TestProviders
 (#36856)

---
 internal/command/testing/test_provider.go | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/internal/command/testing/test_provider.go b/internal/command/testing/test_provider.go
index f62322a0f9..6d83407cb6 100644
--- a/internal/command/testing/test_provider.go
+++ b/internal/command/testing/test_provider.go
@@ -105,6 +105,13 @@ type TestProvider struct {
 	Store *ResourceStore
 }
 
+// NewProvider creates a new TestProvider for use in tests.
+//
+// If you provide an empty or nil *ResourceStore argument this is equivalent to the provider
+// not having provisioned any remote objects prior to the test's events.
+//
+// If you provide a *ResourceStore containing values, those cty.Values represent remote objects
+// that the provider has 'already' provisioned and can return information about immediately in a test.
 func NewProvider(store *ResourceStore) *TestProvider {
 	if store == nil {
 		store = &ResourceStore{
@@ -381,6 +388,10 @@ func (provider *TestProvider) CloseEphemeralResource(providers.CloseEphemeralRes
 
 // ResourceStore manages a set of cty.Value resources that can be shared between
 // TestProvider providers.
+//
+// A ResourceStore represents the remote objects that a test provider is managing.
+// For example, when the test provider gets a ReadResource request it will search
+// the store for a resource with a matching ID. See (*TestProvider).ReadResource.
 type ResourceStore struct {
 	mutex sync.RWMutex