Support the @private JSDoc directive to exclude private APIs from emitted type declarations
#61651
Open
6 tasks done
Comments
@private JSDoc directive to exclude private APIs from type declarations@private JSDoc directive to exclude private APIs from emitted type declarations
|
If I'm not mistaken, it sounds like you should just enable |
|
Thank you for providing advice on the matter! I personally would prefer if I could stick to standard JSDoc directives like However, I've just tried this but when I add I'm using tsc v5.8.3, do you have any idea what could be wrong here? 🤔
/**
* @param {Map<import('../types.js').XastNode, import('../types.js').XastParent>} parents
* @returns {Required<import('css-select').Options<import('../types.js').XastNode & { children?: any }, import('../types.js').XastElement>>['adapter']}
* @internal
*/
export function createAdapter(parents) {
{
"extends": "./tsconfig.json",
"compilerOptions": {
"noEmit": false,
"declaration": true,
"emitDeclarationOnly": true,
"outDir": "types/",
"stripInternal": true,
},
"include": [
"lib/svgo-node.js",
"lib/svgo.js"
]
}
/**
* @internal
* @param {Map<import('../types.js').XastNode, import('../types.js').XastParent>} parents
* @returns {Required<import('css-select').Options<import('../types.js').XastNode & { children?: any }, import('../types.js').XastElement>>['adapter']}
*/
export function createAdapter(parents: Map<import("../types.js").XastNode, import("../types.js").XastParent>): Required<import("css-select").Options<import("../types.js").XastNode & {
children?: any;
}, import("../types.js").XastElement>>["adapter"]; |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
🔍 Search Terms
"private jsdoc"
✅ Viability Checklist
⭐ Suggestion
Could properties, functions, and classes annotated with the
@privateJSDoc directive be omitted from the emitted declarations?tsc should throw an error if a symbol is marked as
@private, but is actually imported/exported from another declaration file or used in the signature of another symbol like a function parameter or return type. (And therefore isn't actually an internal API.)I'm wary this may break some projects if implemented without an opt-in, so it may require an option to enable this behavior, to preserve backward compatibility.
📃 Motivating Example
I maintain a svgo, a library that is written in JavaScript and typed with JSDoc directives, and uses tsc to emit declaration files.
As a library normally has an intended public API, afaik there's no need to distribute type declarations for the internal API.
💻 Use Cases
This is just to reduce the amount of type declarations served to developers if they aren't needed, reducing the size of the package on npm a little.
No workaround is currently needed, assuming the project is a module that uses
exportsrather thanmain, as we can limit the public API ourselves. The extra types do not cause any harm, it just makes the final package a little bigger.For projects that use
maininstead ofexportsin theirpackage.json, this may leak more private APIs that end-users may accidently consume and believe to be part of the public interface.The text was updated successfully, but these errors were encountered: