typedoc

typedoc copied to clipboard

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

1. "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"
  }
}

4. yarn typedoc

Environment

• Typedoc version: 0.23.15
• TypeScript version: 4.8.4
• Node.js version: v16.15.0
• OS: MacOS Ventura

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.

Corollary:

class Foo { /** @hidden */ method() {} }
class Bar { /** {@inheritDoc Foo.method} */ baz() {} }

Should Bar.baz be hidden? This feels like a likely mistake to me...

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:

• Handle visibility flags (@private, @protected. @public)
• Handle module renames (@module)
• Remove excluded tags & comment discovery tags (@module, @packageDocumentation)
• Copy comments for type parameters from the parent container

Resolve begin:

• Remove hidden reflections

Resolve:

• Apply @label tag
• Copy comments on signature containers to the signature if signatures don't already have a comment and then remove the comment on the container.
• Copy comments from signatures to parameters and type parameters (again? why?)
• Apply @group and @category tags

Resolve end:

• Copy auto inherited comments from heritage clauses
• Handle @inheritDoc
• Resolve @link tags to point to target reflections