Use Go 1.19 Documentation Linking

[bflad]

Module version

v0.10.0

Use-cases

The recent Go 1.19 release includes updates to the Go Doc Comments syntax for supporting links. This updated documentation support is already live on the Go Package website. There are a few places in our Go documentation in which we reference other types, fields, etc. by name, but not by link. It can help provider developers to use the link syntax so they can view the desired content directly, rather than needing to indirectly find it.

Proposal

Where there are Go documentation comments that reference other types or fields, wrap those in square braces ([, ]), which will enable the link.

For example, the current tfsdk.Resource comment is:

// Resource represents an instance of a managed resource type. This is the core
// interface that all resources must implement.
//
// 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.

Updating to the below should appropriately link things:

// Resource represents an instance of a managed resource type. This is the core
// interface that all resources must implement.
//
// 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.

References

• https://go.dev/doc/comment