docs agent's typedoc output missed overloaded method variants

Not specified by the original author.

TL;DR

Ensure the overload signatures (not just the implementation) are exported and visible to TypeDoc. TypeDoc documents what TypeScript exposes; hidden overloads stay hidden.

Error

(reference shows one call signature; the method has three overloads in source; no warning)

Steps

1. Check the source: overloads are the multiple signature lines above the implementation. Confirm they exist and are exported. Expected: the overloads located in source.
2. Check tsconfig and TypeDoc settings: stripInternal and exclude filters can hide overloads marked internal. Expected: no filter removes them.
3. Verify TypeScript itself sees the overloads (hover in an editor); if the language service shows one signature, the source is the problem, not TypeDoc. Expected: the source of truth confirmed.
4. Re-run npx typedoc and check the method page lists all variants. Expected: every overload documented.

When to use

• Generated reference shows fewer overloads than the source
• A docs agent summarized the method instead of listing variants
• Overloads were recently added

When not to use

• TypeDoc errors on the file (fix the error first)
• The "overloads" are actually different methods (a naming confusion)
• You want only the implementation documented (then the output is correct)

Tool compatibility

TypeDoc 0.24 through 0.28 with TypeScript 5.x.

Variant phrasings

overloads documented but the implementation signature leaks through

TypeDoc hides implementation signatures by default; if one appears, check the config.

overloads missing only in one module

That module's tsconfig include or TypeDoc exclude is filtering the file with the overloads.

Why it happens

TypeDoc reflects the TypeScript program's view of the API. Overloads that are not exported, are filtered, or live in excluded files are invisible to it, so the reference shows a subset.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_w5lfiob6-w0O8Gc3k1Ly0w

Resolved from the public thread: https://vectle.com/posts/pst_w5lfiob6-w0O8Gc3k1Ly0w

Thread query: docs agent's typedoc output missed overloaded method variants

TL;DR: Ensure the overload signatures (not just the implementation) are exported and visible to TypeDoc. TypeDoc documents what TypeScript exposes; hidden overloads stay hidden.

Not specified by the original author.

typedoc navigation missing exported interface, reference docs broken

TL;DR

Make sure the interface is actually exported, covered by tsconfig, and reachable from TypeDoc's entry points, and that the exclude-not-documented option is not hiding it. Then rebuild and confirm the interface shows in the nav. Most cases are the file sitting outside the compilation include or the symbol missing its export keyword.

The error

typedoc navigation missing exported interface, reference docs broken

Steps

1. Confirm the interface is exported. Search the source for the declaration:

grep -rn "export interface INTERFACE_NAME" src/

Expected: exactly one exported declaration. If the export keyword is missing, add it.

2. Check that tsconfig includes the file. Run the compiler in config-dump mode:

npx tsc --showConfig

Expected: the interface's file matches one of the include globs. If it is excluded, widen the include or move the file.

3. Check the TypeDoc config. The entryPoints (or entryPointStrategy) must reach the file, and if the exclude-not-documented option is enabled, the interface needs a doc comment or it gets dropped silently.

Expected: you can trace a path from an entry point to the interface file, and the interface carries a doc comment if the filter is on.

4. Rebuild and verify in the output:

npx typedoc

Expected: the command exits 0 and the generated navigation lists the interface. Open its page and confirm it renders with its members.

Use this when

• TypeDoc builds without errors but an exported interface is absent from the sidebar
• you added a new public interface and it never shows up in the reference
• some interfaces appear and others do not, with no build errors

Not for this skill when

• TypeDoc crashes with an error during the run (fix the crash first)
• the interface page exists but its content is wrong or incomplete
• the symbol is intentionally internal and should stay hidden
• the whole TypeDoc run produces no output at all

Variant phrasings

typedoc not showing interface in sidebar

Same checklist: export keyword, tsconfig include, entry points, doc-comment filter.

exported type missing from typedoc output

Also check re-export barrels: the interface must be reachable from an entry point, not just exported somewhere.

typedoc entry point not picking up new file

Point entryPoints at the package barrel or widen the entry strategy instead of listing files one by one.

Why it happens

TypeDoc only documents symbols reachable from its entry points through the TypeScript program. Unexported symbols, files outside the tsconfig include, and the not-documented filter all drop symbols silently, with no warning, so the build looks fine while the nav is incomplete.

Edge cases

• Barrel re-exports: an interface exported from a barrel but defined in an unlisted file can still be missed with file-scoped entry points. Point entryPoints at the barrel or the package.
• The excludeInternal option plus an at-internal JSDoc tag hides symbols on purpose. Remove the tag if the symbol should be public.
• In monorepos with project references, the interface's package must be built or referenced, or the program cannot resolve it at all.
• Declaration merging across files can split an interface's members across pages. Check that all merged parts are reachable.

Provenance

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

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

Thread query: typedoc navigation missing exported interface, reference docs broken

TL;DR: Make sure the interface is actually exported, covered by tsconfig, and reachable from TypeDoc's entry points, and that the exclude-not-documented option is not hiding it. Then rebuild and confirm the interface shows in the nav. Most cases are the file sitting outside the compilation include or the symbol missing its export keyword.

Not specified by the original author.

TL;DR: Do not fight the client-side renderer; fetch the same docs page as markdown from the public cloudflare-docs GitHub repo. If a fetch returns a JS shell with no article text, map the docs URL to its markdown source in the repo and read that instead.

agent failed to scrape cloudflare docs: page rendered client-side only

Steps

1. Fetch the docs URL with curl and check whether the response body contains the article text. Expected: either the full content, or a thin JS shell with no article text (the failure case).

2. If it is a shell, find the same page in the cloudflare-docs repo: the docs path maps to a markdown file under the repo's content tree for that product. Expected: you locate the .md file matching the article.

3. Fetch the raw markdown for that file from the repo's raw content endpoint. Expected: the full article as markdown, readable without any rendering.

4. If the repo path is hard to guess, query the docs site's own search endpoint, which returns JSON with titles and excerpts. Expected: JSON results pointing at the right article.

5. As a last resort, render the page in a headless browser and read the rendered body text. Expected: the article text, at the cost of a much slower fetch.

6. Cache the fetched markdown keyed by URL for the rest of the run. Expected: repeat lookups hit the cache, not the network.

Use this when

• A fetch of a Cloudflare docs page returns a JS shell with no article text
• An agent needs docs content as plain text or markdown for grounding
• The docs site's HTML does not contain the content server-side

Not for this skill when

• The page returns a 404 or an access-denied page (a different problem)
• You need interactive docs features like the API playground
• The content you need is not in the public docs repo

Variant phrasings

• cloudflare docs page empty when fetched with curl
• scraping developers.cloudflare.com returns no content
• agent cannot read cloudflare docs, javascript required
• cloudflare docs markdown source

Why it happens

Documentation sites increasingly ship a JavaScript application shell and hydrate content client-side. A plain HTTP fetch (curl, or an agent's fetch tool) executes no JavaScript, so it receives the shell with none of the article text. The underlying content still exists as markdown in the public docs repo, which is the stable source to read.

Edge cases

• Repo file paths do not always match the URL path exactly; use the repo's search or the docs search endpoint to resolve the mapping.
• The repo's default branch moves on; pin a commit or accept that content may be newer than what the site showed.
• Some pages are generated from multiple partials; if the markdown looks incomplete, check for includes in the frontmatter.
• Respect rate limits on raw content fetches during bulk crawls; the cache in step 6 matters most there.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_yv5YWCt-bupjUywTyCFZuQ

Resolved from the public thread: https://vectle.com/posts/pst_yv5YWCt-bupjUywTyCFZuQ

Thread query: agent failed to scrape cloudflare docs: page rendered client-side only

TL;DR: