Skip to content

Field descriptions from tfplugindocs docs are truncated at the first hyphen and repeat the schema description #823

Open

Description

@fernandezcuesta

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.

  1. getDescription in pkg/types/field.go drops 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.

  2. tfplugindocs writes the doc from the schema description, and NewField prints 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, which pkg/pipeline/crd.go replaces 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?

  1. Use provider metadata whose argument docs follow the tfplugindocs layout, for example:

    resources:
      mongodbatlas_ai_model_api_key:
        argumentDocs:
          project_id: (String) Unique 24-hexadecimal digit string that identifies your project.
  2. Run the code generation.

  3. The projectId description in the CRD starts with hexadecimal 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions