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

vscode/src/codeReader/languages/exceptions.test.ts

@@ -8,7 +8,7 @@ import { celeryRule } from '../rules/celery'
 import { dataclassRule } from '../rules/dataclass'
 import { enumRule } from '../rules/enum'
 import { sqlalchemyRule } from '../rules/sqlalchemy'
-import { flatSegments, outline, propertyLines, readFixture, runtime, WASM_DIR, withBlocks } from '../testSupport'
+import { flatSegments, inlineOf, outline, propertyLines, readFixture, runtime, WASM_DIR, withBlocks } from '../testSupport'
 import { pythonZhTranslator } from '../translators/pythonZh'
 import { typescriptZhTranslator } from '../translators/typescriptZh'
 import { createPythonAdapter } from './python'
@@ -55,7 +55,7 @@ function lines(list: readonly BlockView[], name: string): string[] {
 function linkedSegments(rows: PropertyRow[]): Segment[] {
   const pieces: Inline[] = rows.flatMap(row => [
     ...('markdown' in row.value ? [] : row.value),
-    ...(row.items ?? []).flatMap(item => item.cells.flat()),
+    ...(row.items ?? []).flatMap(item => item.cells.flatMap(inlineOf)),
   ])
   return flatSegments(pieces).filter(segment => segment.offset !== undefined)
 }

vscode/src/codeReader/languages/rust.test.ts

@@ -4,7 +4,7 @@ import { toBlockViews } from '../blockView'
 import { blockMarks } from '../diff/viewDiff'
 import { rustImplRule } from '../rules/rustImpl'
 import { isCrateRoot } from '../rules/rustTree'
-import { readFixture, viewLines, WASM_DIR, withBlocks } from '../testSupport'
+import { propertyLines, readFixture, viewLines, WASM_DIR, withBlocks } from '../testSupport'
 import { rustZhTranslator } from '../translators/rustZh'
 import { createRustAdapter } from './rust'
 
@@ -249,6 +249,45 @@ describe('rust 注释', () => {
     expect(viewLines([list[2]!])).toContain('  说明: 读出这个账号的凭证。')
   })
 
+  it('连着几行的 /// 是一段说明，块标签拆开放：@param 进参数表、@return 跟在返回后面、@throws 成异常表；结构体的 @param 对到字段', async () => {
+    const source = [
+      '/// 读出这个账号的凭证。',
+      '///',
+      '/// @param account 账号',
+      '/// @param ttl 写错的名字',
+      '/// @return 没存过时是 None',
+      '/// @throws [StoreError] 存储读不了',
+      'pub fn load(account: &str) -> Option<String> { None }',
+      '',
+      '/// 一个凭证。',
+      '/// @param token 访问令牌',
+      'pub struct Credential { pub token: String, scope: u8 }',
+    ].join('\n')
+    const list = await views(source)
+    const fn = card(list, 'function')
+    const struct = card(list, 'class')
+    expect('properties' in fn && propertyLines(fn.properties)).toEqual([
+      '名称: load',
+      '说明: 读出这个账号的凭证。',
+      '对不上的参数: 1 个',
+      '  ttl | 写错的名字',
+      '可见性: 公开',
+      '输入参数: 1 个',
+      '  account | &str | 账号',
+      '返回: Option<String> — 没存过时是 None',
+      '异常: 1 个',
+      '  [StoreError] | 存储读不了',
+    ])
+    expect('properties' in struct && propertyLines(struct.properties)).toEqual([
+      '名称: Credential',
+      '说明: 一个凭证。',
+      '可见性: 公开',
+      '字段: 2 个',
+      '  token | String | 公开 | 访问令牌',
+      '  scope | u8 | 本模块 | ',
+    ])
+  })
+
   it('在 mod、impl 身体里同一套', async () => {
     const source = [
       'mod store {',