microsoft / microsoft/TypeScript

Adding jsdoc to overriding method makes inherited jsdoc disappear

Open
#43,506 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Domain: JSDoc Needs Proposal Suggestion
Dominant language
Go
Stars
111k
Forks
14.3k
Avg merge
2d 4h
Merged PRs (30d)
132

Description

When adding doc to a class for API level, if we add more doc inside the implementation, we lost some documentation !
ex here, i add * @example $AA.method() and if i add tag @implement or any others in the childClass, we lost documentations from parent and for the API level.

This image show tag:@example $AA.method() is removed!, because we add more doc in AA.method !
image

The expected behavior should be look like this (push docs and no replace) .
Work only if we add in parent , but should work if we add in child class.
image

  • VS Code Version:
    Version : 1.55.0 (user setup)
    Commit : c185983a683d14c396952dd432459097bc7f757f
    Date : 2021-03-30T16:01:55.261Z
    Electron : 11.3.0
    Chrome : 87.0.4280.141
    Node.js : 12.18.3
    V8 : 8.7.220.31-electron.0
    OS : Windows_NT x64 10.0.19042

Steps to Reproduce:

Add doc to AA.method will remove some docs in the A.method

abstract class A {
	/**  `method` to be implement for the class AA
	 * @example $AA.method()
	 */
	abstract method(): any;
}

class AA extends A {
	/**
	 * @implements more info on the implementation
	 */
	method() {
		throw new Error('Method not implemented.');
	}
}

Does this issue occur when all extensions are disabled?: Yes

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the abstract A/AA example in VS Code with extensions disabled and compare the rendered documentation for the inherited method. Trace the TypeScript language-service handling of JSDoc on overridden methods, then add or update a regression test if the relevant test area is found. Done means implementation documentation is added without removing inherited examples or API-level text.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
compilers, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.