Backfill standard library function & parameter descriptions

Depends on https://github.com/zclconf/go-cty/pull/137

This PR backfills all the descriptions for functions and parameters used by Terraform.

Background

To be able to offer auto-completion of available functions and their signatures within the Terraform language server, we need a longer description for both a function and each parameter.

More information is available in the TF-418: Support Functions in Language Server RFC.

Changes

I've added a description to all function definitions, and their parameters that Terraform is currently using. The function description is a direct copy of the documentation's first paragraph. I mostly made up the parameter descriptions based on text snippets. It might make sense to have a technical writer make sure those provide the right context.

gofmt made some changes to a few larger comments.

UX

This is how the descriptions appear in VS Code.

Auto-completion of functions

2022-10-12 10 21 48

The function signature is displayed to the right and below that the description.

Signature help for a function

2022-10-12 11 02 13

CleanShot 2022-10-12 at 17 31 20@2x

The parameter descriptions (1) appears below the function signature and the function description (2) below that.

On hover over a function

2022-10-12 11 02 40

The function description is displayed below the signature.

Misc

I don't know if it's helpful to others, but I've created a list of all Terraform functions, their introduction, and their source to track the work.

zclconf / go-cty