microsoft / microsoft/TypeScript

Adding jsdoc to overriding method makes inherited jsdoc disappear

オープン
#43,506 コメント 3 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

Domain: JSDoc Needs Proposal Suggestion
主要言語
Go
スター
111k
フォーク
14.3k
平均マージ
2日 4時間
マージ済み PR(30日)
132

説明

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

コントリビューションガイド

コントリビューションガイドを開く

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

調査の方向性

拡張機能を無効にした状態で VS Code で抽象 A/AA の例を再現し、継承されたメソッドのレンダリングされたドキュメントを比較します。オーバーライドされたメソッド上の JSDoc を TypeScript language-service がどのように処理するかを追跡し、関連するテスト領域が見つかった場合は回帰テストを追加または更新します。継承された例や API レベルのテキストを削除せずに実装ドキュメントが追加されていれば完了です。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
typescript
領域
compilers, tooling
issue の種類
バグ
難易度
4/5
見積もり時間
3〜5日
活発さ
停滞
明瞭さ
おおむね明確
初心者へのやさしさ
35/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。