📝 use typedoc for js-core#4801
Conversation
- Replace per-sub-path API tables with a brief sub-path index table - Add "Internal package" notice to README - Update AGENTS.md: point to typedoc.json instead of README for new sub-paths - Add typedoc.json to configure API doc generation entry points
thomas-lebeau
changed the title
| appears in the generated API docs | ||
| 6. Add a row for the new sub-path to the table in `README.md` | ||
|
|
||
| ## Current sub-paths |
There was a problem hiding this comment.
suggestion: Can we remove this section? We already have it in README.md
The sub-paths table in AGENTS.md is now redundant — README.md was already updated to point to typedoc for the API reference. Remove the duplicate table and the step that asked contributors to maintain it.
Bundles Sizes Evolution
|
🎉 All green!🧪 All tests passed 🎯 Code Coverage (details) 🔗 Commit SHA: 49c2ce0 | Docs | Datadog PR Page | Give us feedback! |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 49c2ce0218
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| > **Internal package.** This package is intended for use by Datadog SDKs only and is not designed | ||
| > for direct consumption by end users. APIs may change without notice outside of Datadog SDK | ||
| > releases. |
There was a problem hiding this comment.
issue: This package is still documented in packages/js-core/AGENTS.md as an independently versioned, semver-stable package consumed outside the Browser SDK, with breaking changes explicitly disallowed outside a major release. Publishing a README that says the APIs “may change without notice” contradicts that guarantee for npm consumers and maintainers, and can lead external users to treat stable sub-path APIs as unsupported/internal even though the package policy says otherwise.
Useful? React with 👍 / 👎.
2 participants
Motivation
The
@datadog/js-coreREADME contained extensive inline API tables for all sub-paths (/time,/monitor,/util). These tables are hard to maintain and drift out of sync as the API evolves. The generated TypeDoc documentation at https://datadoghq.dev/browser-sdk/ is the canonical, always-up-to-date API reference.Changes
README.mdwith a brief sub-path summary table and a link to the generated API docsREADME.mdto clarify this package is not for direct end-user consumptiontypedoc.jsonconfig file topackages/js-core/listing the entry points for API doc generationAGENTS.mdto drop the README maintenance instructions (inline API tables) and replace with guidance to add sub-paths totypedoc.jsoninsteadTest instructions
js-coresub-paths appear:time,monitor, andutilsub-paths are listed with their exportsREADME.mdto confirm the sub-path table and typedoc link are clearpackages/js-core/typedoc.jsonlists all three current entry pointsChecklist