starlark/types: documentation review

starlark/types/attribute.go

@@ -19,9 +19,9 @@ type sString = starlark.String
 //         Attribute is a reference to an argument of a Resource. Used mainly
 //         for Computed arguments of Resources.
 //
-//         Attribute behaves as type of the argument represented, this means
-//         that their can be assigned to other resource arguments of the same
-//         type. And, if the type is a list are indexables.
+//         Attribute behaves as the type of the argument represented, this means
+//         that them can be assigned to other resource arguments of the same
+//         type. And, if the type is a list are indexable.
 //
 //         examples:
 //           attribute.star

starlark/types/backend.go

@@ -66,11 +66,10 @@ func MakeBackend(
 //   outline: types
 //     types:
 //       Backend
-//         A [backend](https://www.terraform.io/docs/backends/index.html) in
-//         Terraform determines how state is loaded and how an operation such
-//         as apply is executed. The backend can be set as a `tf.backend` or
-//         be used standalone to read the same from this or other Terraform
-//         configuration.
+//         The part of Terraform's core that determines how Terraform stores
+//         state and performs operations (like plan, apply, import, etc.).
+//         Terraform has multiple [backends](https://www.terraform.io/docs/backends/index.html)
+//         to choose from, which can be configured in a variety of ways.
 //
 //         fields:
 //           __kind__ string
@@ -209,10 +208,11 @@ func (b *Backend) Type() string {
 //   outline: types
 //     types:
 //       State
-//         State about your managed infrastructure and configuration. This
-//         [state](https://www.terraform.io/docs/state/index.html) is used by
-//         Terraform to map real world resources to your configuration, keep
-//         track of metadata, and to improve performance for large infrastructures.
+//         Terraform's cached information about your managed infrastructure
+//         and configuration. This [state](https://www.terraform.io/docs/state/index.html)
+//         is used to persistently map the same real world resources to your
+//         configuration from run-to-run, keep track of metadata, and improve
+//         performance for large infrastructures.
 //
 //         State implements a Dict, where the first level are the providers
 //         containing the keys `data` with the data sources and `resources` with
@@ -220,7 +220,7 @@ func (b *Backend) Type() string {
 //
 //         examples:
 //           backend_local.star
-//             An example of how print a resume of providers and resources
+//             An example of how to print a resume of providers and resources
 //             count from the state.
 //
 //         fields:

starlark/types/collection.go

@@ -15,9 +15,9 @@ import (
 //   outline: types
 //     types:
 //       ResourceCollection
-//           ResourceCollection stores and instantiates resources for specific
-//           provider and resource. The resources can be accessed by indexing or
-//           using the built-in method of `dict`.
+//           ResourceCollection stores and instantiates resources for a specific
+//           pair of provider and resource. The resources can be accessed by
+//           indexing or using the built-in method of `dict`.
 //
 //         fields:
 //           __provider__ Provider
@@ -41,7 +41,7 @@ import (
 //                 autogenerated.
 //               values dict
 //                 List of arguments and nested blocks to be set in the new
-//                 resource, this values can be also defined using `kwargs`.
+//                 resource, these values can also be defined using `kwargs`.
 //           search(key="id", value) list
 //             Return all the Resources with the given value in the given key.
 //

starlark/types/evaluate.go

@@ -13,12 +13,12 @@ import (
 //   outline: types
 //     functions:
 //       evaluate(filename, predeclared=None) dict
-//         Evaluates a Starlark file and returns it's global context. Kwargs may
+//         Evaluates a Starlark file and returns its global context. Kwargs may
 //         be used to set predeclared.
 //         params:
 //           filename string
 //             Name of the file to execute.
-//           predeclared? dict
+//           predeclared dict
 //             Defines the predeclared context for the execution. Execution does
 //             not modify this dictionary
 //

starlark/types/provider.go

@@ -63,10 +63,10 @@ func MakeProvider(
 //   outline: types
 //     types:
 //       Provider
-//         Terraform is used to create, manage, and update infrastructure
-//         resources such as physical machines, VMs, network switches,
-//         containers, and more. Almost any infrastructure type can be
-//         represented as a resource in Terraform.
+//         A plugin for Terraform that makes a collection of related resources
+//         available. A provider plugin is responsible for understanding API
+//         interactions with some kind of service and exposing resources based
+//         on that API.
 //
 //         examples:
 //           provider.star
@@ -81,8 +81,8 @@ func MakeProvider(
 //           __type__ string
 //             Type of the resource. Eg.: `aws_instance`
 //           __name__ string
-//             Local name of the provider, if none was provided to the constructor
-//             the name is auto-generated following the partern `id_%s`.  At
+//             Local name of the provider, if none was provided to the constructor,
+//             the name is auto-generated following the pattern `id_%s`.  At
 //             Terraform is called [`alias`](https://www.terraform.io/docs/configuration/providers.html#alias-multiple-provider-instances)
 //           __dict__ Dict
 //             A dictionary containing all set arguments and blocks of the provider.
@@ -234,10 +234,10 @@ func (p *Provider) CompareSameType(op syntax.Token, yv starlark.Value, depth int
 //           __kind__ string
 //             Kind of the resources (`data` or `resource`).
 //           <resource-name> ResourceCollection
-//             It returns a ResourceCollection if the resource name is valid for
+//             Returns a ResourceCollection if the resource name is valid for
 //             the schema of the provider. The resource name should be provided
 //             without the provider prefix, `aws_instance` becomes
-//             just `instance`.
+//             just an `instance`.
 //
 type ResourceCollectionGroup struct {
 	provider    *Provider

starlark/types/resource.go

@@ -159,7 +159,7 @@ func unpackResourceArgs(
 //
 //         methods:
 //           depends_on(resource)
-//             Explicitly declares a dependency with another resource. Use the
+//             Explicitly declares a dependency on another resource. Use the
 //             [depends_on](https://www.terraform.io/docs/configuration/resources.html#depends_on-explicit-resource-dependencies)
 //             meta-argument to handle hidden resource dependencies that
 //             Terraform can't automatically infer.

starlark/types/terraform.go

@@ -13,8 +13,8 @@ import (
 //   outline: types
 //     types:
 //       Terraform
-//         Terraform holds all the configuration defined by an script. A global
-//         variable called `tf` holds the unique instance of Terraform.
+//         Terraform holds all the configuration defined by a script. A global
+//         variable called `tf` contains a unique instance of Terraform.
 //
 //         examples:
 //           tf_overview.star