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

vscode/src/codeReader/diff/viewDiff.ts

@@ -33,7 +33,7 @@ export interface ItemDiff {
   /** 整行是新加的（它下面各层也都是） */
   added?: true
   /** 按列：这一格改成了什么样 */
-  cells?: Record<number, InlinePart[]>
+  cells?: Record<number, TextDiff>
   items?: ItemsDiff
   table?: ItemsDiff
 }
@@ -49,6 +49,8 @@ export interface RowDiff {
   /** 整行是新加的（它下面的子行也都是） */
   added?: true
   value?: TextDiff
+  /** 跟在值后面的说明（PropertyRow.note） */
+  note?: TextDiff
   items?: ItemsDiff
 }
 
@@ -79,7 +81,7 @@ function textWithoutSource(text: PreviewText): PreviewText {
 
 function itemWithoutSource(item: PropertyItem): PropertyItem {
   return {
-    cells: item.cells.map(withoutSource),
+    cells: item.cells.map(textWithoutSource),
     ...(item.items && { items: item.items.map(itemWithoutSource) }),
     ...(item.table && { table: tableWithoutSource(item.table) }),
   }
@@ -93,6 +95,7 @@ function rowWithoutSource(row: PropertyRow): PropertyRow {
   return {
     label: row.label,
     value: textWithoutSource(row.value),
+    ...(row.note && { note: row.note }),
     ...(row.items && { items: row.items.map(itemWithoutSource) }),
     ...(row.columns && { columns: row.columns }),
   }
@@ -175,14 +178,18 @@ export function markdownDiff(before: string, after: string): MarkdownPart[] | un
   })
 }
 
+/** 一段预览文字的字：着色的词拼起来，Markdown 取原文。 */
+function plainText(text: PreviewText): string {
+  return 'markdown' in text ? text.markdown : inlineText(text)
+}
+
 /** 一段预览文字前后两版比：都是着色的词逐截比，都是 Markdown 逐词比；一种换成了另一种时按字逐词比。一样时是 undefined。 */
 export function textDiff(before: PreviewText, after: PreviewText): TextDiff | undefined {
   if (!('markdown' in before) && !('markdown' in after)) {
     const inline = inlineDiff(before, after)
     return inline && { inline }
   }
-  const plain = (text: PreviewText): string => 'markdown' in text ? text.markdown : inlineText(text)
-  const markdown = markdownDiff(plain(before), plain(after))
+  const markdown = markdownDiff(plainText(before), plainText(after))
   return markdown && { markdown }
 }
 
@@ -232,13 +239,13 @@ function addedItem(item: PropertyItem): ItemDiff {
   return { added: true, ...(items && { items }), ...(table && { table }) }
 }
 
-/** 配上的两个子行比：各格逐截比，下一层、套着的表逐行比。一样时是 undefined。 */
+/** 配上的两个子行比：各格逐截 / 逐词比，下一层、套着的表逐行比。一样时是 undefined。 */
 function itemDiff(before: PropertyItem, after: PropertyItem): ItemDiff | undefined {
-  const cells: Record<number, InlinePart[]> = {}
+  const cells: Record<number, TextDiff> = {}
   after.cells.forEach((cell, index) => {
-    const parts = inlineDiff(before.cells[index] ?? [], cell)
-    if (parts)
-      cells[index] = parts
+    const diff = textDiff(before.cells[index] ?? [], cell)
+    if (diff)
+      cells[index] = diff
   })
   const items = itemsDiff(before.items, after.items)
   const table = itemsDiff(before.table?.items, after.table?.items)
@@ -257,7 +264,7 @@ function itemDiff(before: PropertyItem, after: PropertyItem): ItemDiff | undefin
 export function itemsDiff(before: readonly PropertyItem[] | undefined, after: readonly PropertyItem[] | undefined): ItemsDiff | undefined {
   const old = before ?? []
   const now = after ?? []
-  const { toOld, toNew } = pairByKey(old, now, item => inlineText(item.cells[0] ?? []))
+  const { toOld, toNew } = pairByKey(old, now, item => plainText(item.cells[0] ?? []))
   const changed: Record<number, ItemDiff> = {}
   now.forEach((item, index) => {
     const paired = toOld[index]
@@ -270,15 +277,15 @@ export function itemsDiff(before: readonly PropertyItem[] | undefined, after: re
 }
 
 /**
- * 配上的两行比：下面的子行逐行比，值逐截 / 逐词比。子行改了时只标子行：带子行的行，值是子行的汇总（「3 个」「字典 2 项」），
- * 跟着子行变，不另标。一样时是 undefined。
+ * 配上的两行比：下面的子行逐行比，值逐截 / 逐词比，跟在值后面的说明逐词比。子行改了时不标值：带子行的行，值是子行的汇总
+ * （「3 个」「字典 2 项」），跟着子行变，不另标。一样时是 undefined。
  */
 function rowDiff(before: PropertyRow, after: PropertyRow): RowDiff | undefined {
   const items = itemsDiff(before.items, after.items)
-  if (items)
-    return { items }
-  const value = textDiff(before.value, after.value)
-  return value && { value }
+  const note = textDiff(before.note ?? { markdown: '' }, after.note ?? { markdown: '' })
+  const value = items ? undefined : textDiff(before.value, after.value)
+  const diff: RowDiff = { ...(items && { items }), ...(value && { value }), ...(note && { note }) }
+  return Object.keys(diff).length > 0 ? diff : undefined
 }
 
 /** 属性表前后两版比：按属性名配对，配上的比值和子行，多出来的行算新加的，没了的行算删掉的、排回原来的位置。一样时是 undefined。 */