Skip to content

Backtick PackageConfig.Name in PackageStatus.name comment to fix TS doc autolink - #897

Open
Jeremy Rose (jeremyrose-viam) wants to merge 1 commit into
viamrobotics:mainfrom
jeremyrose-viam:fix/packageconfig-name-doc-link
Open

Jeremy Rose (jeremyrose-viam) wants to merge 1 commit into
viamrobotics:mainfrom
jeremyrose-viam:fix/packageconfig-name-doc-link

Conversation

@jeremyrose-viam

@jeremyrose-viam Jeremy Rose (jeremyrose-viam) commented Sep 14, 2026

Copy link
Copy Markdown
Member

tl;dr for human readers

The current line 539 is parsed into a broken link by TypeDoc. The backticks avoid this.

Summary

  • The PackageStatus.name field comment in robot.proto references PackageConfig.Name as plain prose. The TypeScript SDK's TypeDoc build autolinks it because .name is a valid gTLD, producing a broken link (http://PackageConfig.Name) on the published TS SDK docs at ts.viam.dev/classes/robotApi.PackageStatus.html. This was flagged by the TS SDK's scheduled Link Check workflow (run, auto-filed as DOCS-4941).
  • Wrapping the reference in backticks stops TypeDoc's autolinker from treating it as a URL.

Verification

  • Rebuilt the TS SDK's generated proto bindings from this branch and ran typedoc + htmltest locally: the field now renders as <code>PackageConfig.Name</code> with no link, and htmltest passes with 0 errors (previously 2).
  • Checked for regressions in the other SDKs that carry this comment through to published docs:
    • Python (Sphinx autoapi+napoleon): reproduced the exact doc pipeline with the backticked string and built with nitpicky mode (-n) — 0 warnings. Renders as <cite>PackageConfig.Name</cite> (docutils' default role), a harmless cosmetic change.
    • Go (pkg.go.dev): field comments render as raw syntax-highlighted source text, not parsed markdown — backticks just show up as literal characters.
    • C++: the comment text isn't carried into generated bindings at all (protoc strips comments by default), so nothing changes.

Test plan

  • Local TypeDoc + htmltest rebuild confirms the broken link is resolved
  • Local Sphinx repro confirms no Python doc-build regression
  • Confirmed Go and C++ are unaffected

🤖 Generated with Claude Code

@github-actions github-actions Bot added the safe to test committer is a member of this org label Sep 14, 2026
@jeremyrose-viam Jeremy Rose (jeremyrose-viam) added safe to test committer is a member of this org and removed safe to test committer is a member of this org labels Sep 14, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure! Thanks.

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

Labels

safe to test committer is a member of this org

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants