🐛 fix(vscode): 写注释时改已有说明，不再在声明上面另插一行

vscode/src/codeReader/languages/python.ts

@@ -648,6 +648,18 @@ function pythonTokenRole(leaf: Node): TokenRole {
 }
 
 /** Python 语言插件。@param wasmDir 语法包 .wasm 所在目录 */
+/** 函数、类还没有说明时，在主体里插一段 docstring。主体跟声明写在同一行时从第一条语句那一列拆开。 */
+function freshDoc(block: CodeBlock): { line: number, shell: string, breakAt?: number } | undefined {
+  if (block.kind !== 'function' && block.kind !== 'class')
+    return undefined
+  const shell = '"""_"""'
+  const below = block.children.find(child => child.header.startRow > block.header.endRow)
+  if (below)
+    return { line: below.header.startRow, shell }
+  const same = block.children.find(child => child.node.startPosition.row === block.header.endRow)
+  return same ? { line: block.header.endRow, shell, breakAt: same.node.startPosition.column } : undefined
+}
+
 export function createPythonAdapter(wasmDir: string): LanguageAdapter {
   return {
     id: 'python',
@@ -656,6 +668,7 @@ export function createPythonAdapter(wasmDir: string): LanguageAdapter {
     toBlocks: root => withExceptions(attachComments(statements(named(root), 'module', -1), aboutModule), PYTHON_EXCEPTIONS),
     tokenRole: pythonTokenRole,
     lineComment: '#',
+    freshDoc,
     iteration: pythonIteration,
     call: pythonCall,
     displayNames: pythonNameReader,

vscode/src/codeReader/languages/rust.ts

@@ -14,6 +14,7 @@ export function createRustAdapter(wasmDir: string): LanguageAdapter {
     toBlocks: root => attachComments(topBlocks(named(root), -1), aboutModule),
     tokenRole: rustTokenRole,
     lineComment: '//',
+    freshDoc,
   }
 }
 
@@ -35,6 +36,13 @@ const COMMENTS: CommentRules = {
   documents: new Set(['function', 'class', 'trait', 'impl', 'module', 'enum', 'const', 'variable']),
 }
 
+/** 能带说明的项还没有说明时，在它紧上面插 `///`。 */
+function freshDoc(block: CodeBlock): { line: number, shell: string } | undefined {
+  if (!(COMMENTS.documents as ReadonlySet<string>).has(block.kind))
+    return undefined
+  return { line: block.header.startRow, shell: '/// _' }
+}
+
 /** 讲所在模块或 crate 的内部文档注释（`//!`、`/*!`）：写在文件开头是文件的说明，写在 `mod` 身体里交给那个模块。 */
 function aboutModule(comment: CommentBlock): boolean {
   return named(comment.node).some(child => child.type === 'inner_doc_comment_marker')

vscode/src/codeReader/languages/shared.ts

@@ -328,6 +328,32 @@ function ownDoc(block: CodeBlock): Node | undefined {
   }
 }
 
+/** 连着几行的外部文档注释（Rust 的 `///`）是同一段说明，第一条节点带着后面紧挨着的几行；别的说明就是它那个节点。 */
+export function docRun(first: Node): Node[] {
+  const outer = (node: Node): boolean => node.type === 'line_comment' && named(node).some(child => child.type === 'outer_doc_comment_marker')
+  if (!outer(first))
+    return [first]
+  const nodes = [first]
+  for (let next = first.nextSibling; next && outer(next) && next.startPosition.row === nodes.at(-1)!.startPosition.row + 1; next = next.nextSibling)
+    nodes.push(next)
+  return nodes
+}
+
+/** 块自己的说明占的那几行（见 ownDoc，Rust 连着的 `///` 算一整段）。没有说明就没有。 */
+export function explanationSpan(block: CodeBlock): SourceSpan | undefined {
+  const doc = ownDoc(block)
+  if (!doc)
+    return undefined
+  const nodes = docRun(doc)
+  const first = nodes[0]
+  const last = nodes.at(-1)
+  if (!first || !last)
+    return undefined
+  const start = isCommentNode(first) ? commentNodeSpan(first) : nodeSpan(first)
+  const end = isCommentNode(last) ? commentNodeSpan(last) : nodeSpan(last)
+  return { startIndex: start.startIndex, endIndex: end.endIndex, startRow: start.startRow, endRow: end.endRow }
+}
+
 /** 类属性的说明，照源码顺序：讲它的注释（BlockShape.comments）、它这一行行尾的注释、Python 紧跟在后面的属性 docstring。 */
 function fieldDocs(block: CodeBlock): Node[] {
   const trailing = block.node.nextNamedSibling

vscode/src/codeReader/languages/typescript.ts

@@ -636,6 +636,13 @@ function typescriptTokenRole(leaf: Node): TokenRole {
 }
 
 /** TypeScript / TSX / JavaScript / JSX 语言插件。@param wasmDir 语法包 .wasm 所在目录 */
+/** 能带说明的块还没有说明时，在声明紧上面插一段 JSDoc。 */
+function freshDoc(block: CodeBlock): { line: number, shell: string } | undefined {
+  if (!(COMMENTS.documents as ReadonlySet<string>).has(block.kind))
+    return undefined
+  return { line: block.header.startRow, shell: '/** _ */' }
+}
+
 export function createTypeScriptAdapter(wasmDir: string): LanguageAdapter {
   return {
     id: 'typescript',
@@ -649,6 +656,7 @@ export function createTypeScriptAdapter(wasmDir: string): LanguageAdapter {
     toBlocks: (root, _source, languageId) => withExceptions(attachComments(blockReader(TYPED_LANGUAGES.has(languageId))(root), aboutFile), TYPESCRIPT_EXCEPTIONS),
     tokenRole: typescriptTokenRole,
     lineComment: '//',
+    freshDoc,
     call: typescriptCall,
     displayNames: typescriptNameReader,
   }