如何为嵌套TypeScript接口编写文档以支持VS Code提示

问题场景 #

先看示例代码：

/**
 * @description a complex object
 * @property prop1 - a string 
 * @property prop2 - a number argument
 */
interface myObj {
    /** string prop1 */
    prop1: string;
    prop2?: number;
    [key: string]: any
}

interface myfunc {
    /**
     * @description method description
     * @argument foo The first argument
     * @argument {myObj} bar
     */
    some_method: (
        /** simple string argument */
        foo : string,
        /** how to get this to display the description above?  */
        bar : myObj
    ) => void
}

目前已生效的提示：

• 悬浮some_method能看到方法描述和参数注释
• 第一个参数处按Ctrl+Shift+Space显示“simple string argument”
• 打开第二个参数的对象时按Ctrl+Space能提示prop1和prop2
• 悬浮第二个参数内的prop1能看到“string prop1”

存在的两个问题：

1. 在第二个参数的对象内按Ctrl+Shift+Space时，无法显示myObj的完整描述块，而这个带Markdown的描述对这种“预定义属性+自定义键”的类型很有用
2. 在bar : myObj上方的注释里加@标签后，VS Code完全不显示提示；重复写内联注释不仅复用性差，还不支持Markdown

解决方案 #

问题1：让myObj的完整描述在参数对象内显示

直接按以下两步调整：

1. 给myObj写规范的支持Markdown的JSDoc注释：

   /**
    * 一个支持自定义键的复杂对象
    *
    * 内置两个预定义属性，同时允许添加任意键值对：
    * - `prop1`: 必填字符串属性
    * - `prop2`: 可选数字属性
    * @property prop1 - 字符串类型的核心属性
    * @property prop2 - 可选的数字参数属性
    */
   interface myObj {
       /** prop1的具体说明 */
       prop1: string;
       prop2?: number;
       [key: string]: any;
   }
   

2. 在some_method的JSDoc里用@param标签正确关联类型，删掉参数上方的冗余内联注释：

   interface myfunc {
       /**
        * 示例业务方法
        * @param foo 第一个字符串参数，用于XX场景
        * @param bar 符合myObj类型的参数，支持自定义扩展键值
        */
       some_method: (
           foo: string,
           bar: myObj
       ) => void;
   }
   

调整后，当你在bar参数的对象内部（比如输入{后按Ctrl+Shift+Space），VS Code会自动拉取myObj的完整JSDoc描述，包括Markdown格式的内容。

问题2：参数注释加@标签无提示的问题

别在参数上方的内联注释里用JSDoc的@标签（比如@param），这类标签必须统一写在方法的JSDoc块里。如果已经在方法JSDoc中通过@param关联了类型，VS Code会自动复用对应类型的文档，完全不需要重复写内联注释，既省事儿又能支持Markdown格式。

内容的提问来源于stack exchange，提问作者Killerpixler