✨ feat(vscode): 代码阅读把说明里的 @param / @return / @throws 拆到参数表、输出、异常表

vscode/src/codeReader/contract.ts

@@ -579,8 +579,9 @@ export type TokenRole
  * refers：这段讲的是源码里别处的一个名字（那个名字的范围），语言扩展不认得这段自己的位置：写在字符串里的名字
  * （FastAPI 路径 `"/{user_id}"` 里的 user_id 讲的是函数的参数 user_id）。预览把这段当那个名字：⌘ / Ctrl + 点击跳到它的定义，
  * 单击高亮它的各处出现，那个名字的某处出现盖住 refers 时这段也跟着高亮。offset 照旧是这段照抄的位置。
+ * tooltip：悬停这段时看的字（说明里写了、参数表里没有的参数名：「没有这个参数」）。
  */
-export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference, color?: ThemeColor, refers?: SourceRange }
+export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference, color?: ThemeColor, refers?: SourceRange, tooltip?: string }
 
 /**
  * 框的样式，决定框头的图标和框的颜色：
@@ -612,10 +613,37 @@ export type Inline = Segment | SegmentGroup
 
 /**
  * 一段 Markdown 说明文字：注释、JSDoc、docstring 去掉注释符号、引号和共同缩进后的原文，不做别的转换
- * （reStructuredText 的 `:func:`、JSDoc 的 `@param` 都照抄）。预览按 Markdown 渲染成注释色的段落、列表、代码块，源码里的 HTML 当文字显示。
+ * （reStructuredText 的 `:func:` 照抄）。预览按 Markdown 渲染成注释色的段落、列表、代码块，源码里的 HTML 当文字显示；
+ * KDoc 写法的不带路径的引用（`[名字]`、`[类.成员]`）由预览向宿主问它指的定义，问到了能点。
  */
 export interface Markdown { markdown: string }
 
+/** 说明里讲的一个参数（`@param 名字 说明`）：名字照写（`*args`、`...rest` 带着前缀），说明是 Markdown。 */
+export interface DocParam { name: string, text: Markdown }
+
+/**
+ * 说明里讲的一种异常（`@throws 异常 什么时候抛`）。异常写成 Markdown：只写了名字的（`ValueError`、JSDoc 的 `{ValueError}`）
+ * 写成不带路径的引用 `[ValueError]`，`[Foo]`、`[说法](路径#Foo)` 照写；触发条件是 Markdown。
+ */
+export interface DocThrows { exception: Markdown, when: Markdown }
+
+/**
+ * 一段说明（函数、类这些定义的说明，注释，当说明用的字符串）：原文（同 Markdown）按 KDoc 拆成正文和块标签。
+ * 一行以 `@param`、`@return`（`@returns` 同义）、`@throws`（`@exception` 同义）开头算一条标签，后面接着的行（不是空行、不以 `@` 开头）
+ * 续在这条后面，空行结束这条；JSDoc 的 `@param {类型} 名字 - 说明`、`@param [名字] 说明` 也认（类型、横杠去掉）。
+ * 别的标签（`@see`、`@since`）、围栏代码块里的行留在正文里。
+ */
+export interface Doc {
+  /** 摘要和正文：拿掉这几种标签以后的原文；只写了标签时没有。 */
+  body?: Markdown
+  /** 照写的顺序。 */
+  params: DocParam[]
+  /** `@return` 的说明；写了几条时连成一段。 */
+  returns?: Markdown
+  /** 照写的顺序。 */
+  throws: DocThrows[]
+}
+
 /** 预览里显示的一段文字：着色的词（一行译文、属性值），或整段 Markdown 说明（注释块、函数和类的说明）。 */
 export type PreviewText = Inline[] | Markdown
 
@@ -625,9 +653,12 @@ export type PreviewText = Inline[] | Markdown
  */
 export interface Defines { defines?: SourceRange }
 
-/** 属性表里展开的一个子行：几列对齐的格子，例如参数的名称 / 类型 / 默认值、字典一项的键 / 值。 */
+/**
+ * 属性表里展开的一个子行：几列对齐的格子，例如参数的名称 / 类型 / 默认值、字典一项的键 / 值。
+ * 格子是着色的词，或一段 Markdown（参数的说明、异常的触发条件）。
+ */
 export interface PropertyItem extends Defines {
-  cells: Inline[][]
+  cells: PreviewText[]
   /** 展开在这个子行下面的下一层子行（字典 / 对象的值又是字典 / 对象时，它的各项）；一层层可以一直往下套。 */
   items?: PropertyItem[]
   /**
@@ -644,6 +675,8 @@ export interface PropertyItem extends Defines {
 export interface PropertyRow extends Defines {
   label: string
   value: PreviewText
+  /** 跟在值后面的一段说明（Markdown，注释色）：函数输出参数那一行，返回类型后面是说明里的 `@return`。 */
+  note?: Markdown
   items?: PropertyItem[]
   columns?: string[]
 }
@@ -765,8 +798,11 @@ export interface Translator {
   describe: (block: FactBlock, document: SourceDocument) => PropertyRow[]
   /** 一个表达式或类型节点整个翻成一行译文，译法同属性表里的值：库规则翻默认值、类型时借它。 */
   expression: (node: Node, document: SourceDocument) => Inline[]
-  /** 一段说明文字（注释、docstring、当说明用的字符串）去掉注释符号、引号和共同缩进后的 Markdown 原文，同属性表的「说明」；没有文字时没有。 */
-  doc: (node: Node, document: SourceDocument) => Markdown | undefined
+  /**
+   * 一段说明文字（注释、docstring、当说明用的字符串）读成说明（见 Doc）：去掉注释符号、引号和共同缩进后的 Markdown 原文，
+   * 拆出块标签；正文同属性表的「说明」。几条行文档注释连成一段的（Rust 的 `///`），node 是第一条，翻译插件自己往下连。没有文字时没有。
+   */
+  doc: (node: Node, document: SourceDocument) => Doc | undefined
   /** 筛选属性和值叫什么，和属性表里的属性名、值用同一套叫法；不给就都显示 id。 */
   attributeNames?: AttributeNames
 }
@@ -957,8 +993,8 @@ export interface RuleContext {
   displayLanguage?: string
   /** 用当前翻译插件把一个表达式或类型节点翻成一行译文（Translator.expression）：名字带源码下标，能跳到定义、高亮各处出现；没有翻译插件时照抄源码。 */
   translate: (node: Node) => Inline[]
-  /** 用当前翻译插件取一段说明文字（Translator.doc）；没有翻译插件、没有文字时没有。 */
-  doc: (node: Node) => Markdown | undefined
+  /** 用当前翻译插件读一段说明文字（Translator.doc）：正文和块标签；没有翻译插件、没有文字时没有。 */
+  doc: (node: Node) => Doc | undefined
   /**
    * 源码里 name 这个名字（例如 raise 后面的异常类名）指的定义在 index 里认出的那一项，规则从定义处读出的值在 IndexEntry.value 里：
    * 定义由语言扩展查（同 ⌘ + 点击），落在 index 认出的某一项的名字上才算；同一份源码里同名的名字按一处查。