Skip to content

docs(inventory): remove leaked TBD comments - #488

Open
RedZapdos123 wants to merge 1 commit into
opiproject:mainfrom
RedZapdos123:fix/inventory-doc-comments-487
Open

docs(inventory): remove leaked TBD comments#488
RedZapdos123 wants to merge 1 commit into
opiproject:mainfrom
RedZapdos123:fix/inventory-doc-comments-487

Conversation

@RedZapdos123

@RedZapdos123 RedZapdos123 commented Jun 23, 2026

Copy link
Copy Markdown

Description:

Issue #487 reported that placeholder public comments in inventory/inventory.proto were still set to TBD, and those placeholders were leaking into checked-in generated documentation and Swagger output.

MemoryInfo.total_usable_bytes had no real field description, and PCIeDeviceInfo still carried unresolved Type 9 or Type 41 ? text. Because these are public proto comments, the placeholders propagated into inventory/v1/autogen.md, inventory/v1/gen/go/inventory.swagger.json, and generated Go comments.

This PR replaces those placeholders with accurate wording:

  • total_usable_bytes now explains that it is the usable memory capacity available to the system, not current memory usage.
  • PCIeDeviceInfo now describes a single PCIe device discovered on the system instead of keeping unresolved placeholder text.

It also updates the checked-in generated documentation and generated Go comments so the public artifacts no longer expose TBD.

Closes #487.

Checklist:

  • I have updated the source proto comments in inventory/inventory.proto.
  • I have updated the checked-in generated documentation/artifacts affected by those comments.
  • I have run buf lint.
  • I have validated the proto compiles with protoc.
  • I have verified the affected inventory files no longer contain the leaked TBD placeholders.

Before the fix:

inventory/inventory.proto still contained placeholder comments:

// TBD
int64 total_usable_bytes = 2;

// PCI device information
//  TBD: Type 9 or Type 41 ?
//  This structure describes a collection of PCI devices.
message PCIeDeviceInfo {

Those placeholders also appeared in checked-in generated artifacts, for example:

inventory/v1/autogen.md: total_usable_bytes ... TBD
inventory/v1/gen/go/inventory.swagger.json: "title": "TBD"
inventory/v1/autogen.md: PCIeDeviceInfo ... TBD: Type 9 or Type 41 ?
image

After the fix:

The source comments now describe the field and message directly:

// Total usable memory, in bytes, for this array.
// This is the amount of memory the system can actually
// use after accounting for reserved system memory.
// This is not the amount of memory currently in use.
int64 total_usable_bytes = 2;

// PCI device information
//  This structure describes a single PCIe device discovered
//  on the system.
message PCIeDeviceInfo {

The checked in generated docs and generated Go comments were updated to match, and the affected inventory artifacts no longer expose TBD.

image

Signed-off-by: Mridankan Mandal <xerontitan90@gmail.com>
@RedZapdos123
RedZapdos123 requested a review from a team as a code owner June 23, 2026 22:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant