Adapt language ecosystem native API docs practices wherever possible

[edburns]

Work items in this epic deal with bringing all supported languages to parity with Java regarding support for the expected practices for API docs in that language ecosystem.

For Java, we already have:

• https://javadoc.io/doc/com.github/copilot-sdk-java/latest/index.html
• https://github.github.com/copilot-sdk-java/1.0.1/apidocs/com.github.copilot.java/module-summary.html

API Docs Ecosystem Summary

Ecosystem	Doc artifact required to publish?	Auto-hosted docs site	Culture strength
Java	✅ Yes (Maven Central mandate)	javadoc.io (3rd party)	Strong
Node/TS	❌ No	tsdocs.dev (3rd party, unreliable — see note below)	Moderate
Python	❌ No	Read the Docs (opt-in)	Strong convention
Go	❌ No (but comments are the format)	pkg.go.dev (1st party, automatic)	Very strong
.NET	❌ No (but XML doc conventionally included)	fuget.org (3rd party)	Strong
Rust	❌ No (but comments are the format)	docs.rs (1st party, automatic)	Very strong

Note on tsdocs.dev: As of 2026-06-13, tsdocs.dev returns 502 Bad Gateway across all URLs. It is a volunteer-run third-party project with no backing from npm or Microsoft and no SLA. It should not be relied upon as a primary docs hosting solution for @github/copilot-sdk. Self-hosted TypeDoc output (e.g. GitHub Pages from CI) is the only reliable option for TypeScript.

Bottom line: Go and Rust have the closest parity to Java's "publish once, docs appear everywhere" model — but achieved through first-party infrastructure rather than a mandated artifact. Python and .NET have strong doc cultures but require explicit hosting setup. TypeScript is the weakest — tsdocs.dev is unreliable (currently down), so self-hosted docs are a necessity.

[github-actions]

Documentation Gap Analysis

Summary: This epic tracks a documentation gap where only Java currently has published, language-idiomatic API reference documentation. The other SDK languages lack equivalent published API docs in their respective ecosystem formats.

Affected Languages / Documentation

Language	Current State	Expected Format
Java ✅	Javadoc published at [javadoc.io]((javadoc.io/redacted)	Javadoc
Node.js / TypeScript ❌	No published API reference	TypeDoc / TSDoc → HTML
Python ❌	No published API reference	Sphinx / pdoc / pydoc
Go ❌	No published API reference	pkg.go.dev (godoc)
.NET ❌	No published API reference	DocFX / Microsoft Docs XML
Rust ❌	No published API reference	docs.rs / rustdoc

What Content Should Be Added or Improved

For each language SDK, the following work is needed to reach parity with Java:

1. Node.js / TypeScript — Add TSDoc comments to all public APIs in nodejs/src/, configure [TypeDoc]((typedoc.org/redacted) to generate HTML reference docs, and publish them (e.g., via GitHub Pages or a CDN).
2. Python — Add docstrings (Google/NumPy/RST style) to public APIs in python/copilot/, configure a doc generator (Sphinx or pdoc), and publish.
3. Go — Ensure all exported symbols in go/ have godoc-compatible comments; publishing is automatic via pkg.go.dev once the module is indexed.
4. .NET — Add XML <summary>/<param>/<returns> doc comments to public APIs in dotnet/src/, configure DocFX or similar, and publish.
5. Rust — Add /// rustdoc comments to public items in rust/src/; publishing is automatic via docs.rs once the crate is on crates.io.

Suggested Files/Sections to Update

• nodejs/src/client.ts and other public exports — add TSDoc; add typedoc.json config
• python/copilot/**/*.py — add/improve docstrings; add docs/conf.py (Sphinx)
• go/**/*.go — audit exported symbols for godoc comments
• dotnet/src/**/*.cs — add XML doc comments; add docfx.json
• rust/src/lib.rs and public modules — add rustdoc comments
• Each language README.md — add a link to the published API reference once available

The Java implementation serves as the reference model for coverage and style expectations.

Generated by Documentation Handler for issue #1653 · sonnet46 442.8K · ◷