function/stdlib: English-language descriptions for all of the functions

Where it adds information this also includes descriptions of parameters,
but some parameters are intentionally left undescribed because the
function description and argument names are already sufficient to describe
their purpose.

cty/function/stdlib/bool.go

@@ -6,6 +6,7 @@ import (
 )
 
 var NotFunc = function.New(&function.Spec{
+ Description: `Applies the logical NOT operation to the given boolean value.`,
  Params: []function.Parameter{
  {
  Name: "val",
@@ -21,6 +22,7 @@ var NotFunc = function.New(&function.Spec{
 })
 
 var AndFunc = function.New(&function.Spec{
+ Description: `Applies the logical AND operation to the given boolean values.`,
  Params: []function.Parameter{
  {
  Name: "a",
@@ -42,6 +44,7 @@ var AndFunc = function.New(&function.Spec{
 })
 
 var OrFunc = function.New(&function.Spec{
+ Description: `Applies the logical OR operation to the given boolean values.`,
  Params: []function.Parameter{
  {
  Name: "a",

cty/function/stdlib/bytes.go

@@ -30,6 +30,7 @@ func BytesVal(buf []byte) cty.Value {
 // BytesLen is a Function that returns the length of the buffer encapsulated
 // in a Bytes value.
 var BytesLenFunc = function.New(&function.Spec{
+ Description: `Returns the total number of bytes in the given buffer.`,
  Params: []function.Parameter{
  {
  Name: "buf",
@@ -46,6 +47,7 @@ var BytesLenFunc = function.New(&function.Spec{
 
 // BytesSlice is a Function that returns a slice of the given Bytes value.
 var BytesSliceFunc = function.New(&function.Spec{
+ Description: `Extracts a subslice from the given buffer.`,
  Params: []function.Parameter{
  {
  Name: "buf",

cty/function/stdlib/collection.go

@@ -12,6 +12,7 @@ import (
 )
 
 var HasIndexFunc = function.New(&function.Spec{
+ Description: `Returns true if if the given collection can be indexed with the given key without producing an error, or false otherwise.`,
  Params: []function.Parameter{
  {
  Name: "collection",
@@ -37,6 +38,7 @@ var HasIndexFunc = function.New(&function.Spec{
 })
 
 var IndexFunc = function.New(&function.Spec{
+ Description: `Returns the element with the given key from the given collection, or raises an error if there is no such element.`,
  Params: []function.Parameter{
  {
  Name: "collection",
@@ -106,6 +108,7 @@ var IndexFunc = function.New(&function.Spec{
 })
 
 var LengthFunc = function.New(&function.Spec{
+ Description: `Returns the number of elements in the given collection.`,
  Params: []function.Parameter{
  {
  Name: "collection",
@@ -127,6 +130,7 @@ var LengthFunc = function.New(&function.Spec{
 })
 
 var ElementFunc = function.New(&function.Spec{
+ Description: `Returns the element with the given index from the given list or tuple, applying the modulo operation to the given index if it's greater than the number of elements.`,
  Params: []function.Parameter{
  {
  Name: "list",
@@ -206,9 +210,11 @@ var ElementFunc = function.New(&function.Spec{
 // CoalesceListFunc is a function that takes any number of list arguments
 // and returns the first one that isn't empty.
 var CoalesceListFunc = function.New(&function.Spec{
- Params: []function.Parameter{},
+ Description: `Returns the first of the given sequences that has a length greater than zero.`,
+ Params: []function.Parameter{},
  VarParam: &function.Parameter{
  Name: "vals",
+ Description: `List or tuple values to test in the given order.`,
  Type: cty.DynamicPseudoType,
  AllowUnknown: true,
  AllowDynamicType: true,
@@ -270,6 +276,7 @@ var CoalesceListFunc = function.New(&function.Spec{
 // CompactFunc is a function that takes a list of strings and returns a new list
 // with any empty string elements removed.
 var CompactFunc = function.New(&function.Spec{
+ Description: `Removes all empty string elements from the given list of strings.`,
  Params: []function.Parameter{
  {
  Name: "list",
@@ -306,6 +313,7 @@ var CompactFunc = function.New(&function.Spec{
 // ContainsFunc is a function that determines whether a given list or
 // set contains a given single value as one of its elements.
 var ContainsFunc = function.New(&function.Spec{
+ Description: `Returns true if the given value is a value in the given list, tuple, or set, or false otherwise.`,
  Params: []function.Parameter{
  {
  Name: "list",
@@ -364,6 +372,7 @@ var ContainsFunc = function.New(&function.Spec{
 // DistinctFunc is a function that takes a list and returns a new list
 // with any duplicate elements removed.
 var DistinctFunc = function.New(&function.Spec{
+ Description: `Removes any duplicate values from the given list, preserving the order of remaining elements.`,
  Params: []function.Parameter{
  {
  Name: "list",
@@ -399,14 +408,17 @@ var DistinctFunc = function.New(&function.Spec{
 // ChunklistFunc is a function that splits a single list into fixed-size chunks,
 // returning a list of lists.
 var ChunklistFunc = function.New(&function.Spec{
+ Description: `Splits a single list into multiple lists where each has at most the given number of elements.`,
  Params: []function.Parameter{
  {
  Name: "list",
+ Description: `The list to split into chunks.`,
  Type: cty.List(cty.DynamicPseudoType),
  AllowMarked: true,
  },
  {
  Name: "size",
+ Description: `The maximum length of each chunk. All but the last element of the result is guaranteed to be of exactly this size.`,
  Type: cty.Number,
  AllowMarked: true,
  },
@@ -471,6 +483,7 @@ var ChunklistFunc = function.New(&function.Spec{
 // FlattenFunc is a function that takes a list and replaces any elements
 // that are lists with a flattened sequence of the list contents.
 var FlattenFunc = function.New(&function.Spec{
+ Description: `Transforms a list, set, or tuple value into a tuple by replacing any given elements that are themselves sequences with a flattened tuple of all of the nested elements concatenated together.`,
  Params: []function.Parameter{
  {
  Name: "list",
@@ -567,9 +580,11 @@ func flattener(flattenList cty.Value) ([]cty.Value, []cty.ValueMarks, bool) {
 
 // KeysFunc is a function that takes a map and returns a sorted list of the map keys.
 var KeysFunc = function.New(&function.Spec{
+ Description: `Returns a list of the keys of the given map in lexicographical order.`,
  Params: []function.Parameter{
  {
  Name: "inputMap",
+ Description: `The map to extract keys from. May instead be an object-typed value, in which case the result is a tuple of the object attributes.`,
  Type: cty.DynamicPseudoType,
  AllowUnknown: true,
  AllowMarked: true,
@@ -642,6 +657,7 @@ var KeysFunc = function.New(&function.Spec{
 
 // LookupFunc is a function that performs dynamic lookups of map types.
 var LookupFunc = function.New(&function.Spec{
+ Description: `Returns the value of the element with the given key from the given map, or returns the default value if there is no such element.`,
  Params: []function.Parameter{
  {
  Name: "inputMap",
@@ -734,7 +750,8 @@ var LookupFunc = function.New(&function.Spec{
 // If more than one given map or object defines the same key then the one that
 // is later in the argument sequence takes precedence.
 var MergeFunc = function.New(&function.Spec{
- Params: []function.Parameter{},
+ Description: `Merges all of the elements from the given maps into a single map, or the attributes from given objects into a single object.`,
+ Params: []function.Parameter{},
  VarParam: &function.Parameter{
  Name: "maps",
  Type: cty.DynamicPseudoType,
@@ -850,6 +867,7 @@ var MergeFunc = function.New(&function.Spec{
 // ReverseListFunc takes a sequence and produces a new sequence of the same length
 // with all of the same elements as the given sequence but in reverse order.
 var ReverseListFunc = function.New(&function.Spec{
+ Description: `Returns the given list with its elements in reverse order.`,
  Params: []function.Parameter{
  {
  Name: "list",
@@ -898,9 +916,11 @@ var ReverseListFunc = function.New(&function.Spec{
 // preserving the ordering of all of the input lists. Otherwise the result is a
 // set of tuples.
 var SetProductFunc = function.New(&function.Spec{
- Params: []function.Parameter{},
+ Description: `Calculates the cartesian product of two or more sets.`,
+ Params: []function.Parameter{},
  VarParam: &function.Parameter{
  Name: "sets",
+ Description: "The sets to consider. Also accepts lists and tuples, and if all arguments are of list or tuple type then the result will preserve the input ordering",
  Type: cty.DynamicPseudoType,
  AllowMarked: true,
  },
@@ -1038,6 +1058,7 @@ var SetProductFunc = function.New(&function.Spec{
 // SliceFunc is a function that extracts some consecutive elements
 // from within a list.
 var SliceFunc = function.New(&function.Spec{
+ Description: `Extracts a subslice of the given list or tuple value.`,
  Params: []function.Parameter{
  {
  Name: "list",
@@ -1159,9 +1180,10 @@ func sliceIndexes(args []cty.Value) (int, int, bool, error) {
 // ValuesFunc is a function that returns a list of the map values,
 // in the order of the sorted keys.
 var ValuesFunc = function.New(&function.Spec{
+ Description: `Returns the values of elements of a given map, or the values of attributes of a given object, in lexicographic order by key or attribute name.`,
  Params: []function.Parameter{
  {
- Name: "values",
+ Name: "mapping",
  Type: cty.DynamicPseudoType,
  AllowMarked: true,
  },
@@ -1226,6 +1248,7 @@ var ValuesFunc = function.New(&function.Spec{
 // ZipmapFunc is a function that constructs a map from a list of keys
 // and a corresponding list of values.
 var ZipmapFunc = function.New(&function.Spec{
+ Description: `Constructs a map from a list of keys and a corresponding list of values, which must both be of the same length.`,
  Params: []function.Parameter{
  {
  Name: "keys",

cty/function/stdlib/conversion.go

@@ -1,6 +1,7 @@
 package stdlib
 
 import (
+ "fmt"
  "strconv"
 
  "github.com/zclconf/go-cty/cty"
@@ -18,6 +19,7 @@ import (
 // a tuple.
 func MakeToFunc(wantTy cty.Type) function.Function {
  return function.New(&function.Spec{
+ Description: fmt.Sprintf("Converts the given value to %s, or raises an error if that conversion is impossible.", wantTy.FriendlyName()),
  Params: []function.Parameter{
  {
  Name: "v",

cty/function/stdlib/csv.go

@@ -11,6 +11,7 @@ import (
 )
 
 var CSVDecodeFunc = function.New(&function.Spec{
+ Description: `Parses the given string as Comma Separated Values (as defined by RFC 4180) and returns a map of objects representing the table of data, using the first row as a header row to define the object attributes.`,
  Params: []function.Parameter{
  {
  Name: "str",

cty/function/stdlib/datetime.go

@@ -12,6 +12,7 @@ import (
 )
 
 var FormatDateFunc = function.New(&function.Spec{
+ Description: `Formats a timestamp given in RFC 3339 syntax into another timestamp in some other machine-oriented time syntax, as described in the format string.`,
  Params: []function.Parameter{
  {
  Name: "format",
@@ -205,6 +206,7 @@ var FormatDateFunc = function.New(&function.Spec{
 
 // TimeAddFunc is a function that adds a duration to a timestamp, returning a new timestamp.
 var TimeAddFunc = function.New(&function.Spec{
+ Description: `Adds the duration represented by the given duration string to the given RFC 3339 timestamp string, returning another RFC 3339 timestamp.`,
  Params: []function.Parameter{
  {
  Name: "timestamp",

cty/function/stdlib/format.go

@@ -18,6 +18,7 @@ import (
 //go:generate gofmt -w format_fsm.go
 
 var FormatFunc = function.New(&function.Spec{
+ Description: `Constructs a string by applying formatting verbs to a series of arguments, using a similar syntax to the C function \"printf\".`,
  Params: []function.Parameter{
  {
  Name: "format",
@@ -45,6 +46,7 @@ var FormatFunc = function.New(&function.Spec{
 })
 
 var FormatListFunc = function.New(&function.Spec{
+ Description: `Constructs a list of strings by applying formatting verbs to a series of arguments, using a similar syntax to the C function \"printf\".`,
  Params: []function.Parameter{
  {
  Name: "format",

cty/function/stdlib/general.go

@@ -9,6 +9,7 @@ import (
 )
 
 var EqualFunc = function.New(&function.Spec{
+ Description: `Returns true if the two given values are equal, or false otherwise.`,
  Params: []function.Parameter{
  {
  Name: "a",
@@ -32,6 +33,7 @@ var EqualFunc = function.New(&function.Spec{
 })
 
 var NotEqualFunc = function.New(&function.Spec{
+ Description: `Returns false if the two given values are equal, or true otherwise.`,
  Params: []function.Parameter{
  {
  Name: "a",
@@ -55,7 +57,8 @@ var NotEqualFunc = function.New(&function.Spec{
 })
 
 var CoalesceFunc = function.New(&function.Spec{
- Params: []function.Parameter{},
+ Description: `Returns the first of the given arguments that isn't null, or raises an error if there are no non-null arguments.`,
+ Params: []function.Parameter{},
  VarParam: &function.Parameter{
  Name: "vals",
  Type: cty.DynamicPseudoType,

cty/function/stdlib/json.go

@@ -7,6 +7,7 @@ import (
 )
 
 var JSONEncodeFunc = function.New(&function.Spec{
+ Description: `Returns a string containing a JSON representation of the given value.`,
  Params: []function.Parameter{
  {
  Name: "val",
@@ -39,6 +40,7 @@ var JSONEncodeFunc = function.New(&function.Spec{
 })
 
 var JSONDecodeFunc = function.New(&function.Spec{
+ Description: `Parses the given string as JSON and returns a value corresponding to what the JSON document describes.`,
  Params: []function.Parameter{
  {
  Name: "str",