From 967585a2169c930c7907233c817e92903ce8c6ff Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Tue, 11 Oct 2022 17:35:12 +0200 Subject: [PATCH 01/12] Add a description field to the function spec --- cty/function/function.go | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/cty/function/function.go b/cty/function/function.go index c00a0e7f..565f9ce3 100644 --- a/cty/function/function.go +++ b/cty/function/function.go @@ -14,6 +14,9 @@ type Function struct { // Spec is the specification of a function, used to instantiate // a new Function. type Spec struct { + // Description is an optional description for the function specification. + Description string + // Params is a description of the positional parameters for the function. // The standard checking logic rejects any calls that do not provide // arguments conforming to this definition, freeing the function @@ -344,3 +347,8 @@ func (f Function) VarParam() *Parameter { ret := *f.spec.VarParam return &ret } + +// Description returns a human-readable description of the function. +func (f Function) Description() string { + return f.spec.Description +} From 0928a707d0277f9dc524565952b06dd8f4656414 Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Tue, 11 Oct 2022 17:35:43 +0200 Subject: [PATCH 02/12] Add a description field to function parameters --- cty/function/argument.go | 3 +++ 1 file changed, 3 insertions(+) diff --git a/cty/function/argument.go b/cty/function/argument.go index 5a26c275..61a1cf97 100644 --- a/cty/function/argument.go +++ b/cty/function/argument.go @@ -10,6 +10,9 @@ type Parameter struct { // value, but callers may use it for documentation, etc. Name string + // Description is an optional description for the argument. + Description string + // A type that any argument for this parameter must conform to. // cty.DynamicPseudoType can be used, either at top-level or nested // in a parameterized type, to indicate that any type should be From 46323e436fe9ddb17bb84acf076d359a6d321004 Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Tue, 11 Oct 2022 17:41:59 +0200 Subject: [PATCH 03/12] Annotate collection functions --- cty/function/stdlib/collection.go | 68 +++++++++++++++++++++++-------- 1 file changed, 51 insertions(+), 17 deletions(-) diff --git a/cty/function/stdlib/collection.go b/cty/function/stdlib/collection.go index a91821e9..1202a7d2 100644 --- a/cty/function/stdlib/collection.go +++ b/cty/function/stdlib/collection.go @@ -127,15 +127,18 @@ var LengthFunc = function.New(&function.Spec{ }) var ElementFunc = function.New(&function.Spec{ + Description: "element retrieves a single element from a list.", Params: []function.Parameter{ { Name: "list", + Description: "The input list.", Type: cty.DynamicPseudoType, AllowMarked: true, }, { - Name: "index", - Type: cty.Number, + Name: "index", + Description: "Index to get; it must be a non-negative integer.", + Type: cty.Number, }, }, Type: func(args []cty.Value) (cty.Type, error) { @@ -206,9 +209,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: "coalescelist takes any number of list arguments and returns the first one that isn't empty.", + Params: []function.Parameter{}, VarParam: &function.Parameter{ Name: "vals", + Description: "Any number of lists.", Type: cty.DynamicPseudoType, AllowUnknown: true, AllowDynamicType: true, @@ -270,10 +275,12 @@ 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: "compact takes a list of strings and returns a new list with any empty string elements removed.", Params: []function.Parameter{ { - Name: "list", - Type: cty.List(cty.String), + Name: "list", + Description: "The list of strings.", + Type: cty.List(cty.String), }, }, Type: function.StaticReturnType(cty.List(cty.String)), @@ -306,14 +313,17 @@ 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: "contains determines whether a given list or set contains a given single value as one of its elements.", Params: []function.Parameter{ { - Name: "list", - Type: cty.DynamicPseudoType, + Name: "list", + Description: "A list to search in.", + Type: cty.DynamicPseudoType, }, { - Name: "value", - Type: cty.DynamicPseudoType, + Name: "value", + Description: "The value to search for.", + Type: cty.DynamicPseudoType, }, }, Type: function.StaticReturnType(cty.Bool), @@ -364,10 +374,12 @@ 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: "distinct takes a list and returns a new list with any duplicate elements removed.", Params: []function.Parameter{ { - Name: "list", - Type: cty.List(cty.DynamicPseudoType), + Name: "list", + Description: "The input list.", + Type: cty.List(cty.DynamicPseudoType), }, }, Type: func(args []cty.Value) (cty.Type, error) { @@ -399,14 +411,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: "chunklist splits a single list into fixed-size chunks, returning a list of lists.", Params: []function.Parameter{ { Name: "list", + Description: "The input list.", Type: cty.List(cty.DynamicPseudoType), AllowMarked: true, }, { Name: "size", + Description: "The chunk length.", Type: cty.Number, AllowMarked: true, }, @@ -471,9 +486,11 @@ 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: "flatten takes a list and replaces any elements that are lists with a flattened sequence of the list contents.", Params: []function.Parameter{ { Name: "list", + Description: "The input list.", Type: cty.DynamicPseudoType, AllowMarked: true, }, @@ -567,9 +584,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: "keys takes a map and returns a list containing the keys from that map.", Params: []function.Parameter{ { Name: "inputMap", + Description: "The input map.", Type: cty.DynamicPseudoType, AllowUnknown: true, AllowMarked: true, @@ -734,9 +753,11 @@ 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: "merge takes an arbitrary number of maps or objects, and returns a single map or object that contains a merged set of elements from all arguments.", + Params: []function.Parameter{}, VarParam: &function.Parameter{ Name: "maps", + Description: "Two or more maps or objects.", Type: cty.DynamicPseudoType, AllowDynamicType: true, AllowNull: true, @@ -850,9 +871,11 @@ 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: "reverse 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.", Params: []function.Parameter{ { Name: "list", + Description: "The input sequence.", Type: cty.DynamicPseudoType, AllowMarked: true, }, @@ -898,9 +921,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: "The setproduct function finds all of the possible combinations of elements from all of the given sets by computing the Cartesian product.", + Params: []function.Parameter{}, VarParam: &function.Parameter{ Name: "sets", + Description: "Two or more sets as input.", Type: cty.DynamicPseudoType, AllowMarked: true, }, @@ -1038,19 +1063,23 @@ 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: "slice extracts some consecutive elements from within a list.", Params: []function.Parameter{ { Name: "list", + Description: "The input list.", Type: cty.DynamicPseudoType, AllowMarked: true, }, { - Name: "start_index", - Type: cty.Number, + Name: "start_index", + Description: "The inclusive start index.", + Type: cty.Number, }, { - Name: "end_index", - Type: cty.Number, + Name: "end_index", + Description: "The exclusive end index.", + Type: cty.Number, }, }, Type: func(args []cty.Value) (cty.Type, error) { @@ -1159,9 +1188,11 @@ 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: "values takes a map and returns a list containing the values of the elements in that map.", Params: []function.Parameter{ { Name: "values", + Description: "The input map.", Type: cty.DynamicPseudoType, AllowMarked: true, }, @@ -1226,14 +1257,17 @@ 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: "zipmap constructs a map from a list of keys and a corresponding list of values.", Params: []function.Parameter{ { Name: "keys", + Description: "The list of string keys.", Type: cty.List(cty.String), AllowMarked: true, }, { Name: "values", + Description: "The list of values.", Type: cty.DynamicPseudoType, AllowMarked: true, }, From 52046fc685352ec213d47c6cab0dfd05837131a2 Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Tue, 11 Oct 2022 17:42:11 +0200 Subject: [PATCH 04/12] Annotate CSV functions --- cty/function/stdlib/csv.go | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/cty/function/stdlib/csv.go b/cty/function/stdlib/csv.go index 339d04db..0c521527 100644 --- a/cty/function/stdlib/csv.go +++ b/cty/function/stdlib/csv.go @@ -11,10 +11,12 @@ import ( ) var CSVDecodeFunc = function.New(&function.Spec{ + Description: "csvdecode decodes a string containing CSV-formatted data and produces a list of maps representing that data.", Params: []function.Parameter{ { - Name: "str", - Type: cty.String, + Name: "str", + Description: "A string containing CSV-formatted data.", + Type: cty.String, }, }, Type: func(args []cty.Value) (cty.Type, error) { From 7d3b58535f64b745469b14e0664abd8ae74bb822 Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Tue, 11 Oct 2022 17:42:26 +0200 Subject: [PATCH 05/12] Annotate datetime functions --- cty/function/stdlib/datetime.go | 70 ++++++++++++++++++--------------- 1 file changed, 38 insertions(+), 32 deletions(-) diff --git a/cty/function/stdlib/datetime.go b/cty/function/stdlib/datetime.go index 1ceffcf6..a82ee6ce 100644 --- a/cty/function/stdlib/datetime.go +++ b/cty/function/stdlib/datetime.go @@ -12,14 +12,17 @@ import ( ) var FormatDateFunc = function.New(&function.Spec{ + Description: "formatdate converts a timestamp into a different time format.", Params: []function.Parameter{ { - Name: "format", - Type: cty.String, + Name: "format", + Description: "A string that includes formatting sequences.", + Type: cty.String, }, { - Name: "time", - Type: cty.String, + Name: "time", + Description: "A string conforming to the RFC 3339 \"Date and Time format\" syntax.", + Type: cty.String, }, }, Type: function.StaticReturnType(cty.String), @@ -205,14 +208,17 @@ 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: "timeadd adds a duration to a timestamp, returning a new timestamp.", Params: []function.Parameter{ { - Name: "timestamp", - Type: cty.String, + Name: "timestamp", + Description: "A string conforming to the RFC 3339 \"Date and Time format\" syntax.", + Type: cty.String, }, { - Name: "duration", - Type: cty.String, + Name: "duration", + Description: "duration is a string representation of a time difference, consisting of sequences of number and unit pairs, like \"1.5h\" or \"1h30m\".", + Type: cty.String, }, }, Type: function.StaticReturnType(cty.String), @@ -240,30 +246,30 @@ var TimeAddFunc = function.New(&function.Spec{ // // The full set of supported mnemonic sequences is listed below: // -// YY Year modulo 100 zero-padded to two digits, like "06". -// YYYY Four (or more) digit year, like "2006". -// M Month number, like "1" for January. -// MM Month number zero-padded to two digits, like "01". -// MMM English month name abbreviated to three letters, like "Jan". -// MMMM English month name unabbreviated, like "January". -// D Day of month number, like "2". -// DD Day of month number zero-padded to two digits, like "02". -// EEE English day of week name abbreviated to three letters, like "Mon". -// EEEE English day of week name unabbreviated, like "Monday". -// h 24-hour number, like "2". -// hh 24-hour number zero-padded to two digits, like "02". -// H 12-hour number, like "2". -// HH 12-hour number zero-padded to two digits, like "02". -// AA Hour AM/PM marker in uppercase, like "AM". -// aa Hour AM/PM marker in lowercase, like "am". -// m Minute within hour, like "5". -// mm Minute within hour zero-padded to two digits, like "05". -// s Second within minute, like "9". -// ss Second within minute zero-padded to two digits, like "09". -// ZZZZ Timezone offset with just sign and digit, like "-0800". -// ZZZZZ Timezone offset with colon separating hours and minutes, like "-08:00". -// Z Like ZZZZZ but with a special case "Z" for UTC. -// ZZZ Like ZZZZ but with a special case "UTC" for UTC. +// YY Year modulo 100 zero-padded to two digits, like "06". +// YYYY Four (or more) digit year, like "2006". +// M Month number, like "1" for January. +// MM Month number zero-padded to two digits, like "01". +// MMM English month name abbreviated to three letters, like "Jan". +// MMMM English month name unabbreviated, like "January". +// D Day of month number, like "2". +// DD Day of month number zero-padded to two digits, like "02". +// EEE English day of week name abbreviated to three letters, like "Mon". +// EEEE English day of week name unabbreviated, like "Monday". +// h 24-hour number, like "2". +// hh 24-hour number zero-padded to two digits, like "02". +// H 12-hour number, like "2". +// HH 12-hour number zero-padded to two digits, like "02". +// AA Hour AM/PM marker in uppercase, like "AM". +// aa Hour AM/PM marker in lowercase, like "am". +// m Minute within hour, like "5". +// mm Minute within hour zero-padded to two digits, like "05". +// s Second within minute, like "9". +// ss Second within minute zero-padded to two digits, like "09". +// ZZZZ Timezone offset with just sign and digit, like "-0800". +// ZZZZZ Timezone offset with colon separating hours and minutes, like "-08:00". +// Z Like ZZZZZ but with a special case "Z" for UTC. +// ZZZ Like ZZZZ but with a special case "UTC" for UTC. // // The format syntax is optimized mainly for generating machine-oriented // timestamps rather than human-oriented timestamps; the English language From 93de2220b0b09a5d810ec517fe5d362d7c417f08 Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Tue, 11 Oct 2022 17:42:42 +0200 Subject: [PATCH 06/12] Annotate format functions --- cty/function/stdlib/format.go | 82 +++++++++++++++++++---------------- 1 file changed, 44 insertions(+), 38 deletions(-) diff --git a/cty/function/stdlib/format.go b/cty/function/stdlib/format.go index 8b177589..f7ae42b7 100644 --- a/cty/function/stdlib/format.go +++ b/cty/function/stdlib/format.go @@ -18,16 +18,19 @@ import ( //go:generate gofmt -w format_fsm.go var FormatFunc = function.New(&function.Spec{ + Description: "The format function produces a string by formatting a number of other values according to a specification string.", Params: []function.Parameter{ { - Name: "format", - Type: cty.String, + Name: "format", + Description: "A string that includes formatting sequences.", + Type: cty.String, }, }, VarParam: &function.Parameter{ - Name: "args", - Type: cty.DynamicPseudoType, - AllowNull: true, + Name: "args", + Description: "Arguments to the format string.", + Type: cty.DynamicPseudoType, + AllowNull: true, }, Type: function.StaticReturnType(cty.String), Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) { @@ -45,14 +48,17 @@ var FormatFunc = function.New(&function.Spec{ }) var FormatListFunc = function.New(&function.Spec{ + Description: "formatlist produces a list of strings by formatting a number of other values according to a specification string.", Params: []function.Parameter{ { - Name: "format", - Type: cty.String, + Name: "format", + Description: "A string that includes formatting sequences.", + Type: cty.String, }, }, VarParam: &function.Parameter{ Name: "args", + Description: "Arguments to the format string. Can be a mixture of list and non-list arguments.", Type: cty.DynamicPseudoType, AllowNull: true, AllowUnknown: true, @@ -186,32 +192,32 @@ var FormatListFunc = function.New(&function.Spec{ // // It supports the following "verbs": // -// %% Literal percent sign, consuming no value -// %v A default formatting of the value based on type, as described below. -// %#v JSON serialization of the value -// %t Converts to boolean and then produces "true" or "false" -// %b Converts to number, requires integer, produces binary representation -// %d Converts to number, requires integer, produces decimal representation -// %o Converts to number, requires integer, produces octal representation -// %x Converts to number, requires integer, produces hexadecimal representation -// with lowercase letters -// %X Like %x but with uppercase letters -// %e Converts to number, produces scientific notation like -1.234456e+78 -// %E Like %e but with an uppercase "E" representing the exponent -// %f Converts to number, produces decimal representation with fractional -// part but no exponent, like 123.456 -// %g %e for large exponents or %f otherwise -// %G %E for large exponents or %f otherwise -// %s Converts to string and produces the string's characters -// %q Converts to string and produces JSON-quoted string representation, -// like %v. +// %% Literal percent sign, consuming no value +// %v A default formatting of the value based on type, as described below. +// %#v JSON serialization of the value +// %t Converts to boolean and then produces "true" or "false" +// %b Converts to number, requires integer, produces binary representation +// %d Converts to number, requires integer, produces decimal representation +// %o Converts to number, requires integer, produces octal representation +// %x Converts to number, requires integer, produces hexadecimal representation +// with lowercase letters +// %X Like %x but with uppercase letters +// %e Converts to number, produces scientific notation like -1.234456e+78 +// %E Like %e but with an uppercase "E" representing the exponent +// %f Converts to number, produces decimal representation with fractional +// part but no exponent, like 123.456 +// %g %e for large exponents or %f otherwise +// %G %E for large exponents or %f otherwise +// %s Converts to string and produces the string's characters +// %q Converts to string and produces JSON-quoted string representation, +// like %v. // // The default format selections made by %v are: // -// string %s -// number %g -// bool %t -// other %#v +// string %s +// number %g +// bool %t +// other %#v // // Null values produce the literal keyword "null" for %v and %#v, and produce // an error otherwise. @@ -223,10 +229,10 @@ var FormatListFunc = function.New(&function.Spec{ // is used. A period with no following number is invalid. // For examples: // -// %f default width, default precision -// %9f width 9, default precision -// %.2f default width, precision 2 -// %9.2f width 9, precision 2 +// %f default width, default precision +// %9f width 9, default precision +// %.2f default width, precision 2 +// %9.2f width 9, precision 2 // // Width and precision are measured in unicode characters (grapheme clusters). // @@ -243,10 +249,10 @@ var FormatListFunc = function.New(&function.Spec{ // The following additional symbols can be used immediately after the percent // introducer as flags: // -// (a space) leave a space where the sign would be if number is positive -// + Include a sign for a number even if it is positive (numeric only) -// - Pad with spaces on the left rather than the right -// 0 Pad with zeros rather than spaces. +// (a space) leave a space where the sign would be if number is positive +// + Include a sign for a number even if it is positive (numeric only) +// - Pad with spaces on the left rather than the right +// 0 Pad with zeros rather than spaces. // // Flag characters are ignored for verbs that do not support them. // From 1dfd594cb06a0998ddadb66da7b9899f6998da56 Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Tue, 11 Oct 2022 17:42:56 +0200 Subject: [PATCH 07/12] Annotate JSON functions --- cty/function/stdlib/json.go | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/cty/function/stdlib/json.go b/cty/function/stdlib/json.go index 02770a65..eb1ee346 100644 --- a/cty/function/stdlib/json.go +++ b/cty/function/stdlib/json.go @@ -7,9 +7,11 @@ import ( ) var JSONEncodeFunc = function.New(&function.Spec{ + Description: "jsonencode encodes a given value to a string using JSON syntax.", Params: []function.Parameter{ { Name: "val", + Description: "The value being encoded.", Type: cty.DynamicPseudoType, AllowDynamicType: true, AllowNull: true, @@ -39,10 +41,12 @@ var JSONEncodeFunc = function.New(&function.Spec{ }) var JSONDecodeFunc = function.New(&function.Spec{ + Description: "jsondecode interprets a given string as JSON, returning a representation of the result of decoding that string.", Params: []function.Parameter{ { - Name: "str", - Type: cty.String, + Name: "str", + Description: "The JSON string being decoded.", + Type: cty.String, }, }, Type: func(args []cty.Value) (cty.Type, error) { From 47c40ec75f5703f1b7bf8499daf812e084e6051a Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Tue, 11 Oct 2022 17:43:08 +0200 Subject: [PATCH 08/12] Annotate number functions --- cty/function/stdlib/number.go | 61 +++++++++++++++++++++++------------ 1 file changed, 41 insertions(+), 20 deletions(-) diff --git a/cty/function/stdlib/number.go b/cty/function/stdlib/number.go index 4effeb7b..2bceba3a 100644 --- a/cty/function/stdlib/number.go +++ b/cty/function/stdlib/number.go @@ -11,9 +11,11 @@ import ( ) var AbsoluteFunc = function.New(&function.Spec{ + Description: "abs returns the absolute value of the given number.", Params: []function.Parameter{ { Name: "num", + Description: "The numeric value to process.", Type: cty.Number, AllowDynamicType: true, AllowMarked: true, @@ -293,9 +295,11 @@ var NegateFunc = function.New(&function.Spec{ }) var MinFunc = function.New(&function.Spec{ - Params: []function.Parameter{}, + Description: "min takes one or more numbers and returns the smallest number from the set.", + Params: []function.Parameter{}, VarParam: &function.Parameter{ Name: "numbers", + Description: "One or more numbers.", Type: cty.Number, AllowDynamicType: true, }, @@ -317,9 +321,11 @@ var MinFunc = function.New(&function.Spec{ }) var MaxFunc = function.New(&function.Spec{ - Params: []function.Parameter{}, + Description: "max takes one or more numbers and returns the greatest number from the set.", + Params: []function.Parameter{}, VarParam: &function.Parameter{ Name: "numbers", + Description: "One or more numbers.", Type: cty.Number, AllowDynamicType: true, }, @@ -363,10 +369,12 @@ var IntFunc = function.New(&function.Spec{ // CeilFunc is a function that returns the closest whole number greater // than or equal to the given value. var CeilFunc = function.New(&function.Spec{ + Description: "ceil returns the closest whole number that is greater than or equal to the given value, which may be a fraction.", Params: []function.Parameter{ { - Name: "num", - Type: cty.Number, + Name: "num", + Description: "The value to round.", + Type: cty.Number, }, }, Type: function.StaticReturnType(cty.Number), @@ -392,10 +400,12 @@ var CeilFunc = function.New(&function.Spec{ // FloorFunc is a function that returns the closest whole number lesser // than or equal to the given value. var FloorFunc = function.New(&function.Spec{ + Description: "floor returns the closest whole number that is less than or equal to the given value, which may be a fraction.", Params: []function.Parameter{ { - Name: "num", - Type: cty.Number, + Name: "num", + Description: "The value to round.", + Type: cty.Number, }, }, Type: function.StaticReturnType(cty.Number), @@ -420,14 +430,17 @@ var FloorFunc = function.New(&function.Spec{ // LogFunc is a function that returns the logarithm of a given number in a given base. var LogFunc = function.New(&function.Spec{ + Description: "log returns the logarithm of a given number in a given base.", Params: []function.Parameter{ { - Name: "num", - Type: cty.Number, + Name: "num", + Description: "The input number.", + Type: cty.Number, }, { - Name: "base", - Type: cty.Number, + Name: "base", + Description: "The logarithmic base to use.", + Type: cty.Number, }, }, Type: function.StaticReturnType(cty.Number), @@ -448,14 +461,17 @@ var LogFunc = function.New(&function.Spec{ // PowFunc is a function that returns the logarithm of a given number in a given base. var PowFunc = function.New(&function.Spec{ + Description: "pow calculates an exponent, by raising its first argument to the power of the second argument.", Params: []function.Parameter{ { - Name: "num", - Type: cty.Number, + Name: "num", + Description: "The base to use.", + Type: cty.Number, }, { - Name: "power", - Type: cty.Number, + Name: "power", + Description: "The exponent to use.", + Type: cty.Number, }, }, Type: function.StaticReturnType(cty.Number), @@ -477,10 +493,12 @@ var PowFunc = function.New(&function.Spec{ // SignumFunc is a function that determines the sign of a number, returning a // number between -1 and 1 to represent the sign.. var SignumFunc = function.New(&function.Spec{ + Description: "signum determines the sign of a number, returning a number between -1 and 1 to represent the sign.", Params: []function.Parameter{ { - Name: "num", - Type: cty.Number, + Name: "num", + Description: "The input number.", + Type: cty.Number, }, }, Type: function.StaticReturnType(cty.Number), @@ -502,14 +520,17 @@ var SignumFunc = function.New(&function.Spec{ // ParseIntFunc is a function that parses a string argument and returns an integer of the specified base. var ParseIntFunc = function.New(&function.Spec{ + Description: "parseint parses the given string as a representation of an integer in the specified base and returns the resulting number.", Params: []function.Parameter{ { - Name: "number", - Type: cty.DynamicPseudoType, + Name: "number", + Description: "The input to parse.", + Type: cty.DynamicPseudoType, }, { - Name: "base", - Type: cty.Number, + Name: "base", + Description: "The base for parsing; it must be between 2 and 62 inclusive.", + Type: cty.Number, }, }, From c1cc9c44326cf3105cf4dc2cec79be7c2e98ec8c Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Tue, 11 Oct 2022 17:43:21 +0200 Subject: [PATCH 09/12] Annotate regex functions --- cty/function/stdlib/regexp.go | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/cty/function/stdlib/regexp.go b/cty/function/stdlib/regexp.go index 2dd6348a..dd54396e 100644 --- a/cty/function/stdlib/regexp.go +++ b/cty/function/stdlib/regexp.go @@ -10,14 +10,17 @@ import ( ) var RegexFunc = function.New(&function.Spec{ + Description: "regex applies a regular expression to a string and returns the matching substrings.", Params: []function.Parameter{ { - Name: "pattern", - Type: cty.String, + Name: "pattern", + Description: "Pattern is a string containing a mixture of literal characters and special matching operators.", + Type: cty.String, }, { - Name: "string", - Type: cty.String, + Name: "string", + Description: "The input string.", + Type: cty.String, }, }, Type: func(args []cty.Value) (cty.Type, error) { @@ -54,14 +57,17 @@ var RegexFunc = function.New(&function.Spec{ }) var RegexAllFunc = function.New(&function.Spec{ + Description: "regexall applies a regular expression to a string and returns a list of all matches.", Params: []function.Parameter{ { - Name: "pattern", - Type: cty.String, + Name: "pattern", + Description: "Pattern is a string containing a mixture of literal characters and special matching operators.", + Type: cty.String, }, { - Name: "string", - Type: cty.String, + Name: "string", + Description: "The input string.", + Type: cty.String, }, }, Type: func(args []cty.Value) (cty.Type, error) { From 9331f62eb07b3366bf1e0ea01c4e02fee0f2d981 Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Tue, 11 Oct 2022 17:43:32 +0200 Subject: [PATCH 10/12] Annotate sequence functions --- cty/function/stdlib/sequence.go | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/cty/function/stdlib/sequence.go b/cty/function/stdlib/sequence.go index 6a6f66b3..05e2417f 100644 --- a/cty/function/stdlib/sequence.go +++ b/cty/function/stdlib/sequence.go @@ -9,9 +9,11 @@ import ( ) var ConcatFunc = function.New(&function.Spec{ - Params: []function.Parameter{}, + Description: "concat takes two or more lists and combines them into a single list.", + Params: []function.Parameter{}, VarParam: &function.Parameter{ Name: "seqs", + Description: "Variable list of lists to merge.", Type: cty.DynamicPseudoType, AllowMarked: true, }, @@ -137,9 +139,11 @@ var ConcatFunc = function.New(&function.Spec{ }) var RangeFunc = function.New(&function.Spec{ + Description: "range generates a list of numbers using a start value, a limit value, and a step value.", VarParam: &function.Parameter{ - Name: "params", - Type: cty.Number, + Name: "params", + Description: "range accepts start, end and step. While start and step are optional.", + Type: cty.Number, }, Type: function.StaticReturnType(cty.List(cty.Number)), Impl: func(args []cty.Value, retType cty.Type) (ret cty.Value, err error) { From 4f32f7226cb46bee9c984b24c5d02ad3e002935d Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Tue, 11 Oct 2022 17:43:44 +0200 Subject: [PATCH 11/12] Annotate set functions --- cty/function/stdlib/set.go | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/cty/function/stdlib/set.go b/cty/function/stdlib/set.go index 29c425ea..e1bba3ef 100644 --- a/cty/function/stdlib/set.go +++ b/cty/function/stdlib/set.go @@ -29,15 +29,18 @@ var SetHasElementFunc = function.New(&function.Spec{ }) var SetUnionFunc = function.New(&function.Spec{ + Description: "The setunion function takes multiple sets and produces a single set containing the elements from all of the given sets.", Params: []function.Parameter{ { Name: "first_set", + Description: "The first set of elements.", Type: cty.Set(cty.DynamicPseudoType), AllowDynamicType: true, }, }, VarParam: &function.Parameter{ Name: "other_sets", + Description: "Other sets for comparison.", Type: cty.Set(cty.DynamicPseudoType), AllowDynamicType: true, }, @@ -48,15 +51,18 @@ var SetUnionFunc = function.New(&function.Spec{ }) var SetIntersectionFunc = function.New(&function.Spec{ + Description: "The setintersection function takes multiple sets and produces a single set containing only the elements that all of the given sets have in common.", Params: []function.Parameter{ { Name: "first_set", + Description: "The first set of elements.", Type: cty.Set(cty.DynamicPseudoType), AllowDynamicType: true, }, }, VarParam: &function.Parameter{ Name: "other_sets", + Description: "Other sets for comparison.", Type: cty.Set(cty.DynamicPseudoType), AllowDynamicType: true, }, @@ -67,14 +73,17 @@ var SetIntersectionFunc = function.New(&function.Spec{ }) var SetSubtractFunc = function.New(&function.Spec{ + Description: "The setsubtract function returns a new set containing the elements from the first set that are not present in the second set.", Params: []function.Parameter{ { Name: "a", + Description: "The first set of elements.", Type: cty.Set(cty.DynamicPseudoType), AllowDynamicType: true, }, { Name: "b", + Description: "The second set of elements.", Type: cty.Set(cty.DynamicPseudoType), AllowDynamicType: true, }, From ff2594b101d16f2e1321054661d2016b591f76cc Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Tue, 11 Oct 2022 17:43:54 +0200 Subject: [PATCH 12/12] Annotate string functions --- cty/function/stdlib/string.go | 100 +++++++++++++++++++++++----------- 1 file changed, 68 insertions(+), 32 deletions(-) diff --git a/cty/function/stdlib/string.go b/cty/function/stdlib/string.go index 43182dd5..29159be6 100644 --- a/cty/function/stdlib/string.go +++ b/cty/function/stdlib/string.go @@ -14,9 +14,11 @@ import ( ) var UpperFunc = function.New(&function.Spec{ + Description: "upper converts all cased letters in the given string to uppercase.", Params: []function.Parameter{ { Name: "str", + Description: "The input string.", Type: cty.String, AllowDynamicType: true, }, @@ -30,9 +32,11 @@ var UpperFunc = function.New(&function.Spec{ }) var LowerFunc = function.New(&function.Spec{ + Description: "lower converts all cased letters in the given string to lowercase.", Params: []function.Parameter{ { Name: "str", + Description: "The input string.", Type: cty.String, AllowDynamicType: true, }, @@ -46,9 +50,11 @@ var LowerFunc = function.New(&function.Spec{ }) var ReverseFunc = function.New(&function.Spec{ + Description: "strrev reverses the characters in a string.", Params: []function.Parameter{ { Name: "str", + Description: "The input string.", Type: cty.String, AllowDynamicType: true, }, @@ -97,19 +103,23 @@ var StrlenFunc = function.New(&function.Spec{ }) var SubstrFunc = function.New(&function.Spec{ + Description: "substr extracts a substring from a given string by offset and (maximum) length.", Params: []function.Parameter{ { Name: "str", + Description: "The input string.", Type: cty.String, AllowDynamicType: true, }, { Name: "offset", + Description: "The start offset.", Type: cty.Number, AllowDynamicType: true, }, { Name: "length", + Description: "The maximum length.", Type: cty.Number, AllowDynamicType: true, }, @@ -197,15 +207,18 @@ var SubstrFunc = function.New(&function.Spec{ }) var JoinFunc = function.New(&function.Spec{ + Description: "join produces a string by concatenating together all elements of a given list of strings with the given delimiter.", Params: []function.Parameter{ { - Name: "separator", - Type: cty.String, + Name: "separator", + Description: "Delimiter for joining.", + Type: cty.String, }, }, VarParam: &function.Parameter{ - Name: "lists", - Type: cty.List(cty.String), + Name: "lists", + Description: "A list of elements to join.", + Type: cty.List(cty.String), }, Type: function.StaticReturnType(cty.String), Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) { @@ -244,10 +257,12 @@ var JoinFunc = function.New(&function.Spec{ }) var SortFunc = function.New(&function.Spec{ + Description: "sort takes a list of strings and returns a new list with those strings sorted lexicographically.", Params: []function.Parameter{ { - Name: "list", - Type: cty.List(cty.String), + Name: "list", + Description: "The input list.", + Type: cty.List(cty.String), }, }, Type: function.StaticReturnType(cty.List(cty.String)), @@ -282,14 +297,17 @@ var SortFunc = function.New(&function.Spec{ }) var SplitFunc = function.New(&function.Spec{ + Description: "split produces a list by dividing a given string at all occurrences of a given separator.", Params: []function.Parameter{ { - Name: "separator", - Type: cty.String, + Name: "separator", + Description: "The separator for splitting.", + Type: cty.String, }, { - Name: "str", - Type: cty.String, + Name: "str", + Description: "The input string.", + Type: cty.String, }, }, Type: function.StaticReturnType(cty.List(cty.String)), @@ -311,10 +329,12 @@ var SplitFunc = function.New(&function.Spec{ // ChompFunc is a function that removes newline characters at the end of a // string. var ChompFunc = function.New(&function.Spec{ + Description: "chomp removes newline characters at the end of a string.", Params: []function.Parameter{ { - Name: "str", - Type: cty.String, + Name: "str", + Description: "The input string.", + Type: cty.String, }, }, Type: function.StaticReturnType(cty.String), @@ -327,14 +347,17 @@ var ChompFunc = function.New(&function.Spec{ // IndentFunc is a function that adds a given number of spaces to the // beginnings of all but the first line in a given multi-line string. var IndentFunc = function.New(&function.Spec{ + Description: "indent adds a given number of spaces to the beginnings of all but the first line in a given multi-line string.", Params: []function.Parameter{ { - Name: "spaces", - Type: cty.Number, + Name: "spaces", + Description: "Number of spaces to add.", + Type: cty.Number, }, { - Name: "str", - Type: cty.String, + Name: "str", + Description: "A multiline string to indent.", + Type: cty.String, }, }, Type: function.StaticReturnType(cty.String), @@ -352,10 +375,12 @@ var IndentFunc = function.New(&function.Spec{ // TitleFunc is a function that converts the first letter of each word in the // given string to uppercase. var TitleFunc = function.New(&function.Spec{ + Description: "title converts the first letter of each word in the given string to uppercase.", Params: []function.Parameter{ { - Name: "str", - Type: cty.String, + Name: "str", + Description: "The input string.", + Type: cty.String, }, }, Type: function.StaticReturnType(cty.String), @@ -367,10 +392,12 @@ var TitleFunc = function.New(&function.Spec{ // TrimSpaceFunc is a function that removes any space characters from the start // and end of the given string. var TrimSpaceFunc = function.New(&function.Spec{ + Description: "trimspace removes any space characters from the start and end of the given string.", Params: []function.Parameter{ { - Name: "str", - Type: cty.String, + Name: "str", + Description: "The string that will be trimmed.", + Type: cty.String, }, }, Type: function.StaticReturnType(cty.String), @@ -382,14 +409,17 @@ var TrimSpaceFunc = function.New(&function.Spec{ // TrimFunc is a function that removes the specified characters from the start // and end of the given string. var TrimFunc = function.New(&function.Spec{ + Description: "trim removes the specified set of characters from the start and end of the given string.", Params: []function.Parameter{ { - Name: "str", - Type: cty.String, + Name: "str", + Description: "The string that will be trimmed.", + Type: cty.String, }, { - Name: "cutset", - Type: cty.String, + Name: "cutset", + Description: "Every occurrence of a character in the cutset is removed.", + Type: cty.String, }, }, Type: function.StaticReturnType(cty.String), @@ -403,14 +433,17 @@ var TrimFunc = function.New(&function.Spec{ // TrimPrefixFunc is a function that removes the specified characters from the // start the given string. var TrimPrefixFunc = function.New(&function.Spec{ + Description: "trimprefix removes the specified prefix from the start of the given string.", Params: []function.Parameter{ { - Name: "str", - Type: cty.String, + Name: "str", + Description: "The string that will be trimmed.", + Type: cty.String, }, { - Name: "prefix", - Type: cty.String, + Name: "prefix", + Description: "The prefix that will be removed.", + Type: cty.String, }, }, Type: function.StaticReturnType(cty.String), @@ -424,14 +457,17 @@ var TrimPrefixFunc = function.New(&function.Spec{ // TrimSuffixFunc is a function that removes the specified characters from the // end of the given string. var TrimSuffixFunc = function.New(&function.Spec{ + Description: "trimsuffix removes the specified suffix from the end of the given string.", Params: []function.Parameter{ { - Name: "str", - Type: cty.String, + Name: "str", + Description: "The string that will be trimmed.", + Type: cty.String, }, { - Name: "suffix", - Type: cty.String, + Name: "suffix", + Description: "The suffix that will be removed.", + Type: cty.String, }, }, Type: function.StaticReturnType(cty.String),