docs agent failed on protobuf-generated code, docs incomplete

TL;DR

Generate docs from the .proto source files, not from the generated code. The agent parsed generated stubs where comments are stripped and names are mangled, so messages and fields came out undocumented or misnamed. Fix: feed the .proto files to a protobuf doc generator and publish that output instead of extracting from generated code.

The error

docs agent failed on protobuf-generated code, docs incomplete

Steps

1. Compare the generated docs against the .proto files: check whether message comments, field descriptions, and enum values present in the .proto files are missing from the docs. Expected: you confirm the .proto files have documentation the generated reference lacks.

2. Check what the agent parsed: if it walked the generated .pb files or language-specific stubs, that is the wrong input. Expected: you confirm the extractor input was generated code.

3. Point the pipeline at the .proto sources: run a protobuf documentation generator over the .proto files and their imports. Expected: messages, fields, enums, and services render with their source comments intact.

4. Map the .proto documentation onto the generated client SDK names so readers can move between the API reference and the code they call. Expected: each SDK method links back to its .proto service definition.

5. Re-run doc generation and verify coverage: every message, field, and RPC in the .proto files appears in the docs. Expected: zero missing definitions.

Use this when

• protobuf API reference is missing messages or field descriptions
• the agent parsed generated stubs instead of .proto sources
• enum values and service methods are absent from the docs

Not for this skill when

• the .proto files themselves lack comments (a source documentation problem)
• the issue is gRPC method docs rather than message docs (same fix applies, but check the service blocks first)
• you need docs for hand-written code alongside protobuf (a multi-source pipeline question)

Variant phrasings

• docs agent parsed generated protobuf stubs
• incomplete reference docs for grpc api
• proto file comments missing from generated docs
• protobuf message documentation lost in generation

Why it happens

Code generators optimize for machines: they strip comments, mangle names to language conventions, and split definitions across files. An extractor reading that output inherits all of those losses. The .proto files are the actual source of truth for the API contract.

Edge cases

• Imported .proto files from other repos: resolve the import path the same way the build does, or the doc generator will fail on missing imports.
• Custom options and extensions: document the ones that affect API behavior; skip purely internal codegen options.
• Multiple language SDKs from one .proto set: generate the contract docs once from .proto and link each SDK's method docs to it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Pou1VbnmzbwE9ZnGJbLgMg