Closed
Description
Expected Behavior
Interpreting the JSDoc documentation where it states
By default, if you do not add a JSDoc comment to a symbol, the symbol will inherit documentation from its parent.
I would expect the @internal
annotation to also affect methods of inherited implementations, even if I'm redeclaring them in a child class.
Actual Behavior
Typedoc generates documentation for a method that is marked @internal
in a parent class and redeclared within a child class, even if there are no additional JSDoc comments on the declaration within the child class
Steps to reproduce the bug
-
"typedoc": "0.23.15"
class Foo {
/**
@internal
*/
myInternalMethod(){}
}
class Bar extends Foo {
myInternalMethod(){} // I would expect this to still be stripped from documentation when `excludeInternal` is set to true
}
{
"compilerOptions": {
"target": "ES2019" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'. */,
"module": "ESNext" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */,
"outDir": "dist",
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"strict": true /* Enable all strict type-checking options. */,
"esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
"skipLibCheck": true /* Skip type checking of declaration files. */,
"noUnusedLocals": true,
"forceConsistentCasingInFileNames": true /* Disallow inconsistently-cased references to the same file. */,
"moduleResolution": "node",
"resolveJsonModule": true,
"importsNotUsedAsValues": "error"
},
"exclude": ["dist", "**/*.test.ts"],
"include": ["src/**/*"],
"typedocOptions": {
"entryPoints": ["src/index.ts"],
"excludeInternal": true,
"excludePrivate": true,
"excludeProtected": true,
"excludeExternals": true,
"includeVersion": true,
"out": "docs",
"theme": "default"
}
}
yarn typedoc
Environment
- Typedoc version: 0.23.15
- TypeScript version: 4.8.4
- Node.js version: v16.15.0
- OS: MacOS Ventura
Metadata
Metadata
Assignees
Labels
No labels
Type
Projects
Relationships
Development
No branches or pull requests
Activity
[-]Methods marked with `@internal` show up in the docs for child classes[/-][+]Methods marked with `@internal` show up in the docs for child classes if redeclared[/+]Gerrit0 commentedon Oct 29, 2022
Hmmmm... this is because TypeDoc does removal before all of the logic to copy comments around. This is an unfortunate inconsistency, will be rather annoying to fix.
Worth noting that TypeDoc intentionally does not follow JSDoc's behavior in several places, so using JSDoc's site to guess what TypeDoc will do isn't always safe.
Gerrit0 commentedon Oct 29, 2022
Corollary:
Should
Bar.baz
be hidden? This feels like a likely mistake to me...Gerrit0 commentedon Nov 3, 2022
Current process... rearranging this is going to be tricky to do without breaking things. Probably going to take at least a day dedicated to just this at some point...
During conversion:
@private
,@protected
.@public
)@module
)@module
,@packageDocumentation
)Resolve begin:
Resolve:
@label
tagand then remove the comment on the container.
@group
and@category
tagsResolve end:
@inheritDoc
@link
tags to point to target reflectionsUpdate comment discovery to more closely match TS
8 remaining items