Repository navigation
Description
What happened?
Two problems show up in providers whose Terraform docs are generated by tfplugindocs. These docs list attributes as - `project_id` (String) The description, and the scraper stores (String) The description.
-
getDescriptioninpkg/types/field.godrops everything up to the first-of the doc:func getDescription(s string) string { // Remove dash s = strings.TrimSpace(s)[strings.Index(s, "-")+1:]
The classic registry layout keeps a separator (
- (Optional) The description), so the cut removes it. A tfplugindocs doc has no separator, so the cut lands on the first hyphen inside the text:Upstream doc Generated CRD description (String) Unique 24-hexadecimal digit string that identifies your project, ...hexadecimal digit string that identifies your project, ...(String) Cloud provider scope for this API key. Use "ANY" for a cloud-agnostic scope. ...agnostic scope. Additional cloud values will be supported in future API versions.(Set of String) Human-readable label that ...readable label that ...(Required - AWS) Region of the bucket.AWS) Region of the bucket.The index is also computed on the untrimmed string and used on the trimmed one, so leading whitespace shifts the cut. The scraper trims its values, so this only matters for metadata written some other way.
-
tfplugindocs writes the doc from the schema description, and
NewFieldprints the doc followed by the schema description. When the doc survives, the CRD shows the same sentence twice, the first time behind a type marker the schema already states:projectId: description: |- (String) Unique 24-hexadecimal digit string that identifies your project, also known as groupId in the official documentation. Unique 24-hexadecimal digit string that identifies your project, also known as `groupId` in the official documentation.
The doc is still needed where upjet prints no schema description: nested attribute objects converted from the plugin framework, and the top-level
id, whichpkg/pipeline/crd.goreplaces with a schema that has no description.
In provider-mongodbatlas, +700 CRD field descriptions started with a type marker, and +400 printed the same sentence twice.
How can we reproduce it?
-
Use provider metadata whose argument docs follow the
tfplugindocslayout, for example:resources: mongodbatlas_ai_model_api_key: argumentDocs: project_id: (String) Unique 24-hexadecimal digit string that identifies your project.
-
Run the code generation.
-
The
projectIddescription in the CRD starts withhexadecimal digit string. Without a hyphen in the doc, it prints the sentence twice, once with(String)in front.
For a real case, see crossplane-contrib/provider-mongodbatlas#249. Commit d098517 generates these descriptions, and the later commits work around both problems with a default ResourceOption, cleanArgumentDocs() in config/provider.go.
Activity