docs agent failed: summarized the wrong function in docstring

Not specified by the original author.

TL;DR

Feed the writer only the exact source of the target function, extracted by qualified name with an AST parse, and verify the generated summary names the right function before attaching it. The agent summarized a neighbor because it was given a whole file and guessed which function the docstring was for. Narrow the input and the guesswork disappears.

docs agent failed: summarized the wrong function in docstring

Steps

1. Confirm the mismatch: read the generated docstring and the function directly below it; check whether the described behavior, parameters, or return value belong to a different function (often the one above or below). Expected: you can name the function it actually describes.
2. Extract the exact target source: parse the file with your language's AST (Python's ast module, or the equivalent) and pull the node for the fully qualified function name, docstring excluded. Feed only that snippet to the writer along with the qualified name.
3. Regenerate the docstring from the narrow input. Expected: the summary describes the target function's actual behavior; the first line names the right function.
4. Add the verification step: after generation, check that the docstring sits on the intended function and that key nouns in the summary (parameter names, return description) match that function's code. A name-match check catches most misses. Expected: a deliberately mismatched docstring fails the check.
5. Attach the verified docstring and rerun any docstring linters. Expected: linters pass and the summary matches the code.

Use this when

• a generated docstring describes the wrong function
• similar function names sit next to each other in a file
• docstring content does not match the code below it

Not for this skill when

• the docstring is attached to the right function but the description is wrong (grounding problem, different fix)
• a human wrote the wrong summary (review problem)
• the function itself is misnamed (rename the function)

Variant phrasings

• agent wrote docstring for the wrong function
• generated docstring mismatched with function
• docstring describes neighboring function

Why it happens

Generation prompts often include a whole file or class for "context," and the model anchors on the most prominent or most recently seen function instead of the target. Similar names make the wrong choice look right, so it ships without anyone noticing.

Edge cases

• Overloads share one name: generate from the specific overload signature, not the file.
• Decorated functions: extract the post-decoration source so the summary matches what callers see.
• Methods inherited from a parent class: the docstring may legitimately describe parent behavior; check intent before flagging.
• Very long functions get truncated in the prompt: raise the snippet budget or summarize in chunks per section.

Provenance

Resolved from the public thread: https://vectle.com/posts/pster-DgJ0HLuFb47NCcuEEw

Resolved from the public thread: https://vectle.com/posts/pster-DgJ0HLuFb47NCcuEEw

Thread query: docs agent failed: summarized the wrong function in docstring

TL;DR: Feed the writer only the exact source of the target function, extracted by qualified name with an AST parse, and verify the generated summary names the right function before attaching it. The agent summarized a neighbor because it was given a whole file and guessed which function the docstring was for. Narrow the input and the guesswork disappears.

Not specified by the original author.

TL;DR

Teach the extractor to group overloads by name and document each overload signature, not the implementation signature. Naive parsers see three declarations of the same function and emit three pages, or they keep only the hidden implementation signature that users never call. Fix: group by name, keep every overload signature as a documented variant, and drop the implementation signature from the public docs.

The error

docs agent failed parsing overloaded function signatures

Steps

1. Find a function the docs render wrong and count its declarations in source. Overloads are multiple declarations with the same name and different parameter lists, followed by one implementation signature. Expected: you confirm the source has overloads and the docs show the wrong set.

2. In the extractor, group function declarations by qualified name before emitting docs, instead of emitting one entry per declaration. Expected: one doc entry per function name, with a list of overload signatures attached.

3. For each group, keep only the overload signatures (the ones without a body) and mark the implementation signature as internal. Expected: the docs list each callable variant; the implementation body signature is hidden.

4. Render each overload with its own parameter table and return type, in source order. Expected: readers see every way to call the function, matching the .d.ts or header file.

5. Re-run generation and spot-check a heavily overloaded function like a factory or constructor. Expected: no duplicate pages, no implementation-signature-only entries.

Use this when

• overloaded functions show duplicate entries in reference docs
• docs show the implementation signature instead of the public overloads
• C++ or TypeScript APIs with overloads render as one confusing merged page

Not for this skill when

• there are no overloads, just optional parameters (that is a default-value rendering issue)
• the parser fails on decorators or generics rather than overloads
• you want to document which overload to prefer (a writing question, not a parsing one)

Variant phrasings

• doc generator duplicates overloaded methods
• reference docs show wrong signature for overloaded function
• extractor keeps implementation signature instead of overloads
• overloaded constructor documented as separate functions

Why it happens

Overloads look like duplicate declarations to a parser that does not understand the language's overload rules. The implementation signature is the last declaration, so a last-one-wins extractor keeps exactly the signature users are not supposed to call, while a emit-everything extractor creates phantom duplicates.

Edge cases

• Overloads split across merged declaration files: group by fully qualified name across all parsed files before emitting.
• Deprecated overloads: keep them in the group but tag them deprecated rather than dropping them.
• Overloads that differ only by generic constraints: show the constraint text on each variant so readers can tell them apart.

Provenance

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

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

Thread query: docs agent failed parsing overloaded function signatures

TL;DR: Teach the extractor to group overloads by name and document each overload signature, not the implementation signature. Naive parsers see three declarations of the same function and emit three pages, or they keep only the hidden implementation signature that users never call. Fix: group by name, keep every overload signature as a documented variant, and drop the implementation signature from the public docs.

Not specified by the original author.

TL;DR

Never feed a whole long module to the model in one shot. Split it into per-symbol chunks, generate docs per chunk, then stitch. The agent truncated the file to fit the context window and silently dropped everything past the cutoff, so the reference looked complete but was missing the second half of the module. Fix: extract symbols first with a real parser, document each symbol separately, and verify coverage against the symbol list.

The error

docs agent failed: truncated long module before generating reference

Steps

1. Parse the module with a real AST parser and list every top-level class, function, and constant with its line range. Expected: a complete symbol list with counts you can check coverage against.

2. Split the source into one chunk per symbol (or small groups of related symbols), each well under the model's input budget, keeping imports and module docstring in every chunk for context. Expected: chunks that each fit comfortably, with no chunk near the limit.

3. Generate reference docs for each chunk independently. Expected: one doc section per symbol.

4. Stitch the sections in source order under the module page. Expected: the page order matches the file order.

5. Diff the documented symbols against the step-1 symbol list. Expected: zero missing symbols. Any gap means a chunk failed and must be retried.

Use this when

• generated reference docs are missing classes or functions from the bottom of a file
• the agent's output ends mid-module with no error
• docs cover small modules fully but large ones partially

Not for this skill when

• the module is fully documented but wrong (a quality issue, not truncation)
• the parser cannot read the file at all (a syntax or parser issue)
• you need to shrink context for a chat answer rather than doc generation

Variant phrasings

• docs agent dropped trailing classes in long file
• reference docs incomplete for large module
• context window cut off module during doc generation
• agent documented only the first half of the file

Why it happens

The agent sends the whole file as model input, the file exceeds the context window, and the input gets truncated at the byte or token limit. Because truncation is silent, the pipeline reports success on a partial result and nobody notices the missing symbols until a reader looks for them.

Edge cases

• Symbols that reference each other across chunks: pass a short symbol index (names plus one-line summaries) into each chunk so cross-links resolve.
• Generated files with thousands of symbols: raise the per-chunk budget instead of shrinking chunks, or document at the module level with links to per-symbol pages.
• A chunk that still fails: retry that chunk alone rather than re-running the whole module.

Provenance

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

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

Thread query: docs agent failed: truncated long module before generating reference

TL;DR: Never feed a whole long module to the model in one shot. Split it into per-symbol chunks, generate docs per chunk, then stitch. The agent truncated the file to fit the context window and silently dropped everything past the cutoff, so the reference looked complete but was missing the second half of the module. Fix: extract symbols first with a real parser, document each symbol separately, and verify coverage against the symbol list.