Closed dbanck closed 1 year ago
Hi @dbanck! Thanks for working on this.
This library is a third-party dependency of Terraform rather than actually part of Terraform, and so I considered this proposal from the perspective of cty
's own mission rather than anything Terraform might need. Even putting aside Terraform's need to offer a language server, it does seem reasonable to me that any application embedding cty
's functions concept will probably benefit from something like a language server that would need this metadata, and so I think it's reasonable to add it.
One specific consequence of having the descriptions embedded directly in the function's definition is that there will be no opportunity to separate the human-readable description of a function from the place where it's implemented. This means that the descriptions returned by the functions that Terraform happens to use will be fixed in this codebase and not customizable by Terraform. Since I'm currently wearing my "cty
developer" hat instead of my Terraform hat I'm not going to make a call on whether that's an important consequence or not; I imagine if there is a later requirement for Terraform to use a different description than the one I'd want in this non-HashiCorp library then the Terraform team will find a reasonable technical solution to perform as-needed overrides of the generic descriptions from upstream.
I'm going to merge this now and then I'm going to also merge something like the content of your draft PR because it feels strange to me to release the capability for descriptions without actually including descriptions in the upstream functions. I will probably slightly tweak some of the text you proposed because as you noted those descriptions originate in Terraform's own documentation, which has more specific concerns than this library does when taken alone.
Thanks again!
This PR introduces a new field,
Description
, to the functionsSpec
andParameter
types. I've decoupled this from the actual backfilling of all descriptions, so we and the education team can iterate on the descriptions.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.
Next Steps
go-cty