Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Methods marked with @internal show up in the docs for child classes if redeclared #2084

Closed
lukasIO opened this issue Oct 25, 2022 · 3 comments
Labels
bug Functionality does not match expectation
Milestone

Comments

@lukasIO
Copy link

lukasIO commented Oct 25, 2022

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

Environment

  • Typedoc version: 0.23.15
  • TypeScript version: 4.8.4
  • Node.js version: v16.15.0
  • OS: MacOS Ventura
@lukasIO lukasIO added the bug Functionality does not match expectation label Oct 25, 2022
@lukasIO lukasIO changed the title 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 Oct 25, 2022
@Gerrit0
Copy link
Collaborator

Gerrit0 commented 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
Copy link
Collaborator

Gerrit0 commented Oct 29, 2022

Corollary:

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

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

@Gerrit0
Copy link
Collaborator

Gerrit0 commented 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:

  • 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

@Gerrit0 Gerrit0 mentioned this issue Mar 10, 2023
8 tasks
@Gerrit0 Gerrit0 added this to the v0.26.0 milestone Oct 15, 2023
@Gerrit0 Gerrit0 modified the milestones: v0.27.0, v0.26.2 Jun 23, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Functionality does not match expectation
Projects
None yet
Development

No branches or pull requests

2 participants