✨ feat(vscode): 代码阅读函数块默认折叠，函数说明进属性表「说明」行

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

@@ -20,8 +20,7 @@ const SAMPLE: Outline[] = [
   { at: 4, kind: 'import' },
   { at: 6, kind: 'const' },
   { at: 7, kind: 'variable' },
-  { at: 10, kind: 'function', kids: [
-    { at: 11, kind: 'comment' },
+  { at: [10, 11], kind: 'function', kids: [
     { at: 12, kind: 'comment' },
     { at: 13, kind: 'variable' },
     { at: 14, kind: 'if', kids: [{ at: 15, kind: 'return' }] },
@@ -91,6 +90,42 @@ describe('python 代码块树', () => {
   })
 })
 
+describe('python 函数的 docstring', () => {
+  const source = [
+    'class K:',
+    '    """类说明"""',
+    '    def run(self):  # 行尾',
+    '        # 先说一句',
+    '        """跑一遍。',
+    '',
+    '        细节。',
+    '        """  # 行尾',
+    '        # 真正的注释',
+    '        return 1',
+    'def g(): "单行"',
+  ].join('\n')
+
+  it('算进函数头部、不单独成块，它前面的注释也在头部里；后面的注释照旧成块；类的 docstring 照旧是注释块', async () => {
+    expect(await tree(source)).toEqual([
+      { at: 1, kind: 'class', kids: [
+        { at: 2, kind: 'comment' },
+        { at: [3, 8], kind: 'function', kids: [
+          { at: 9, kind: 'comment' },
+          { at: 10, kind: 'return' },
+        ] },
+      ] },
+      { at: 11, kind: 'function' },
+    ])
+  })
+
+  it('进 facts.doc：是那个字符串节点；没有 docstring 的函数没有', async () => {
+    const found = await facts(source)
+    expect(found[3]).toMatchObject({ name: 'run', doc: '"""跑一遍。\n\n        细节。\n        """' })
+    expect(found[11]).toMatchObject({ name: 'g', doc: '"单行"' })
+    expect(await facts('def f():\n    x = 1\n    """not a docstring"""')).not.toHaveProperty('1.doc')
+  })
+})
+
 describe('python 属性表信息（facts）', () => {
   it('sample.py：import / from import、模块和类里的赋值、函数和方法', async () => {
     const sample = await facts(readFixture('sample.py'))
@@ -99,6 +134,7 @@ describe('python 属性表信息（facts）', () => {
     expect(sample[6]).toEqual({ access: 'public', declarators: [{ name: 'MAX_DEPTH', value: '8' }] })
     expect(sample[10]).toEqual({
       name: 'find_env_files',
+      doc: '"""Return every .env file under root."""',
       access: 'public',
       async: false,
       decorators: [],
@@ -128,6 +164,7 @@ describe('python 属性表信息（facts）', () => {
     })
     expect(routes[29]).toEqual({
       name: 'get_user',
+      doc: '"""获取用户详情。\n\n    管理员可查看任意用户，普通用户只能查看自己。\n    """',
       access: 'public',
       async: true,
       decorators: ['@router.get("/{user_id}", response_model=UserDetailResponse)'],