Skip to content

docs(inventory): remove TBD placeholder comments leaking into generated docs and swagger #487

Description

@RedZapdos123

Description:

Latest main still contains placeholder public comments in inventory/inventory.proto, and those placeholders are propagated into generated documentation and OpenAPI output.

Current behavior:

On latest main, inventory/inventory.proto still has unresolved placeholder comments:

  • inventory/inventory.proto:167
    • // TBD
  • inventory/inventory.proto:172
    • // TBD: Type 9 or Type 41 ?

Because these comments are public proto comments, they leak into generated artifacts that are checked into the repository:

  • inventory/v1/autogen.md:160
    • total_usable_bytes description is TBD
  • inventory/v1/autogen.md:171
    • PCIeDeviceInfo section still says TBD: Type 9 or Type 41 ?
  • inventory/v1/gen/go/inventory.swagger.json:216
    • total_usable_bytes has "title": "TBD"
  • inventory/v1/gen/go/inventory.swagger.json:257
    • PCIeDeviceInfo description still contains TBD: Type 9 or Type 41 ?
  • Generated Go comments also inherit same placeholders:
    • inventory/v1/gen/go/inventory.pb.go:516
    • inventory/v1/gen/go/inventory.pb.go:568
    • v1/gen/go/inventory/inventory.pb.go:498
    • v1/gen/go/inventory/inventory.pb.go:550

Expected behavior:

Public inventory API comments should use final descriptive wording, not unresolved placeholders, and regenerated docs/swagger should no longer expose TBD.

Why this matters:

  • Public API docs look unfinished.
  • Generated Swagger/OpenAPI metadata exposes ambiguous placeholder text.
  • Low risk cleanup: this is documentation/comment quality work, not a wire-format change.

Issue Reproduction:

  1. Check out latest main.
  2. Run:
rg -n "TBD" \
  inventory/inventory.proto \
  inventory/v1/autogen.md \
  inventory/v1/gen/go/inventory.swagger.json \
  inventory/v1/gen/go/inventory.pb.go \
  v1/gen/go/inventory/inventory.pb.go
  1. Observe matches for the placeholder comments and their generated outputs.

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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions