Documentation enhancements from dogfooding(work-in-progress)

[dixler]

Hello!

• Vote on this issue by adding a 👍 reaction
• If you want to implement this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

Issue details

Currently working on https://github.com/pulumi/home/issues/2311

While using the docs, I have the following nitpicks(work-in-progress):

• Add the import statements to the README.md it's convenient for copy pasting the entire import string.

I find myself using the following code example https://github.com/pulumi/pulumi-go-provider/blob/main/examples/file/main.go. Comments in the following places could be helpful

• Possibly add more comments here

  pulumi-go-provider/examples/file/main.go

  Lines 23 to 30 in 1e1e747

  	func provider() p.Provider {
  	return infer.Provider(infer.Options{
  	Resources: []infer.InferredResource{infer.Resource[*File, FileArgs, FileState]()},
  	ModuleMap: map[tokens.ModuleName]tokens.ModuleName{
  	"file": "index",
  	},
  	})
  	}

• Could add a comment to detail the purpose of these are type assertions which help create more helpful compilation errors.

  pulumi-go-provider/examples/file/main.go

  Lines 34 to 42 in 1e1e747

  	var _ = (infer.CustomDelete[FileState])((*File)(nil))
  	var _ = (infer.CustomCheck[FileArgs])((*File)(nil))
  	var _ = (infer.CustomUpdate[FileArgs, FileState])((*File)(nil))
  	var _ = (infer.CustomDiff[FileArgs, FileState])((*File)(nil))
  	var _ = (infer.CustomRead[FileArgs, FileState])((*File)(nil))
  	var _ = (infer.ExplicitDependencies[FileArgs, FileState])((*File)(nil))
  	var _ = (infer.Annotated)((*File)(nil))
  	var _ = (infer.Annotated)((*FileArgs)(nil))
  	var _ = (infer.Annotated)((*FileState)(nil))

• Elaborate on the value that implementing the following interface provides.

  pulumi-go-provider/infer/resource.go

  Lines 145 to 147 in 114b52e

  	// Annotated is used to describe the fields of an object or a resource. Annotated can be
  	// implemented by `CustomResource`s, the input and output types for all resources and
  	// invokes, as well as other structs used the above.

Affected area/feature