Don't declare private fields in user facing definition files
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 5k
- Forks
- 162
- Avg merge
- 17h 24m
- Merged PRs (30d)
- 8
Description
When tsdoc is used from multiple libraries each having a slightly different version, private fields cause type incompatibilites. For example:
src/api-documenter/markdown/CustomMarkdownEmitter.ts:167:7 - error TS2345:
Argument of type
'import("node_modules/@microsoft/tsdoc/lib/nodes/DocDeclarationReference").DocDeclarationReference'
is not assignable to parameter of type
'import("node_modules/@microsoft/api-extractor-model/node_modules/@microsoft/tsdoc/lib/nodes/DocDeclarationReference").DocDeclarationReference'.
Types have separate declarations of a private property '_tagDefinitions'.
This is due to slightly different versions requested by the libraries, as shown in yarn.lock:
"@microsoft/tsdoc@0.12.14":
version "0.12.14"
resolved "https://registry.yarnpkg.com/@microsoft/tsdoc/-/tsdoc-0.12.14.tgz#0e0810a0a174e50e22dfe8edb30599840712f22d"
integrity sha512-518yewjSga1jLdiLrcmpMFlaba5P+50b0TWNFUpC+SL9Yzf0kMi57qw+bMl+rQ08cGqH1vLx4eg9YFUbZXgZ0Q==
"@microsoft/tsdoc@^0.12.14":
version "0.12.18"
resolved "https://registry.yarnpkg.com/@microsoft/tsdoc/-/tsdoc-0.12.18.tgz#7e7aadc7009e57a25fbf6c9f48b44c2fe30ada88"
integrity sha512-3rypGnknRaPGlU4HFx2MorC4zmhoGJx773cVbDfcUgc6zI/PFfFaiWmeRR6JiVyKRrLnU/ZH0pc/6jePzy/QyQ==
Yarn always prefers the newest version possible for each module - however, private fields make even "revision" versions incompatible.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the TypeScript definitions for DocDeclarationReference and the CustomMarkdownEmitter.ts error location, then inspect the conflicting @microsoft/tsdoc entries in yarn.lock. Determine how the user-facing definitions should avoid incompatibility between slightly different TSDoc versions. Done means the reported TS2345 incompatibility no longer occurs when the libraries resolve different revision versions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100