✨ feat(vscode): 代码阅读的注释和函数说明按 Markdown 渲染

vscode/src/codeReader/contract.ts

@@ -110,6 +110,15 @@ export type TokenRole
  */
 export interface Segment { text: string, role: TokenRole, offset?: number }
 
+/**
+ * 一段 Markdown 说明文字：注释、JSDoc、docstring 去掉注释符号、引号和共同缩进后的原文，不做别的转换
+ * （reStructuredText 的 `:func:`、JSDoc 的 `@param` 都照抄）。预览按 Markdown 渲染成注释色的段落、列表、代码块，源码里的 HTML 当文字显示。
+ */
+export interface Markdown { markdown: string }
+
+/** 预览里显示的一段文字：着色的词（一行译文、属性值），或整段 Markdown 说明（注释块、函数的说明）。 */
+export type PreviewText = Segment[] | Markdown
+
 /**
  * 属性表里的一行或一个子行讲的是哪个定义：定义出来的那个名字的节点（取自 facts，例如参数名、导入项的名称和别名、
  * 声明的变量名）在源码里的范围。跳到定义时，定义处落在这个范围里就只闪这一行；不填（第三方翻译插件可以不填）就闪整块。
@@ -119,10 +128,10 @@ export interface Defines { defines?: SourceRange }
 /** 属性表里展开的一个子行：几列对齐的格子，例如参数的名称 / 类型 / 默认值。 */
 export interface PropertyItem extends Defines { cells: Segment[][] }
 
-/** 属性表的一行：左列属性名，右列着色的值；items 是展开在这一行下面的子行（输入参数、导入项）。 */
+/** 属性表的一行：左列属性名，右列着色的值或 Markdown 说明；items 是展开在这一行下面的子行（输入参数、导入项）。 */
 export interface PropertyRow extends Defines {
   label: string
-  value: Segment[]
+  value: PreviewText
   items?: PropertyItem[]
 }
 
@@ -143,8 +152,8 @@ export interface Translator {
   id: string // 'typescript.zh-template'
   label: string // '中文直译'
   languageIds: string[]
-  /** 只翻 header 那一段。 */
-  translate: (block: TextBlock, source: string) => Segment[]
+  /** 只翻 header 那一段；注释块给去掉注释符号的 Markdown 原文。 */
+  translate: (block: TextBlock, source: string) => PreviewText
   /** 函数、导入、常量、变量块 → 属性表。 */
   describe: (block: FactBlock, source: string) => PropertyRow[]
 }