Skip to content

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

Closed
@lukasIO

Description

@lukasIO

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

Activity

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[/+] on Oct 25, 2022
Gerrit0

Gerrit0 commented on Oct 29, 2022

@Gerrit0
Collaborator

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

Gerrit0 commented on Oct 29, 2022

@Gerrit0
Collaborator

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

Gerrit0 commented on Nov 3, 2022

@Gerrit0
Collaborator

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
added this to the v0.26.0 milestone on Oct 15, 2023
modified the milestones: v0.27.0, v0.26.2 on Jun 23, 2024
added a commit that references this issue on Jun 23, 2024
16b2694

8 remaining items

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @lukasIO@Gerrit0

        Issue actions

          Methods marked with `@internal` show up in the docs for child classes if redeclared · Issue #2084 · TypeStrong/typedoc