Go AST 怎样为泛型函数生成类型参数文档

遍历顶层 *ast.FuncDecl，读取 fn.Type.TypeParams，再展开其中每个 Field 的 Names，把共同的 Type 表达式作为约束文本，即可生成泛型函数的类型参数文档。普通值参数在 Params 中，返回值在 Results 中，不能混入类型参数表。

官方文档：https://pkg.go.dev/go/ast#FuncType；分组结构：https://pkg.go.dev/go/ast#Field。

把类型参数文档接入源码处理任务

为仓库自动生成接口说明时，可以在源码变更后执行一个只读的文档提取任务。输入是明确选定的 Go 文件，输出是函数名、类型参数名、约束写法及函数注释。仅生成这些语法内容不需要运行目标程序，也不需要获取部署凭据。

本例处理一份内存源码，便于看清逻辑。扩展到项目目录时，调用方需要决定文件范围、构建标签和重复声明如何处理；不要把遍历所有 .go 文件误称为当前构建的 API 集合。源码任务只读，最终文档写入是另一项明确的输出动作。

读取 TypeParams 并展开约束分组

TypeParams 可以为 nil，表示没有显式类型参数列表。非 nil 时，List 里的一个 Field 可以包含多个名称。例如 A、B 共用 any，K 使用 comparable，应该生成三个条目，而不是按 Field 分组生成两个参数。

下面的完整示例使用 format.Node 保留约束的语法表达，不假设它一定是单个标识符。示例为本次原创，没有执行，也没有提供所谓自动化实测结果。

package main

import (
 "bytes"
 "fmt"
 "go/ast"
 "go/format"
 "go/parser"
 "go/token"
 "html"
)

func main() {
 // A、B 共享约束，K 使用另一个约束；文档应输出三个类型参数。
 const source = `package sample
// Join 描述三个类型参数。
func Join[A, B any, K comparable](a A, b B, key K) {}
func Plain(v int) {}
`
 fset := token.NewFileSet()
 file, err := parser.ParseFile(fset, "sample.go", source,
  parser.ParseComments | parser.SkipObjectResolution)
 if err != nil {
  fmt.Println("解析失败：", err)
  return
 }
 var output bytes.Buffer
 for _, decl := range file.Decls {
  fn, ok := decl.(*ast.FuncDecl)
  if !ok || fn.Recv != nil || fn.Type.TypeParams == nil {
   continue
  }
  fmt.Fprintf(&output, "
%s
\n", html.EscapeString(fn.Name.Name))
  if fn.Doc != nil {
   // 注释来自源码，输出 HTML 时必须转义，不能直接作为标签。
   fmt.Fprintf(&output, "
%s
\n", html.EscapeString(fn.Doc.Text()))
  }
  output.WriteString("
\n")
  for _, field := range fn.Type.TypeParams.List {
   var constraint bytes.Buffer
   if err := format.Node(&constraint, fset, field.Type); err != nil {
    fmt.Println("约束格式化失败：", err)
    return
   }
   for _, name := range field.Names {
    // 每个名字保留一项，共享同一组约束的源码写法。
    fmt.Fprintf(&output, "
%s: %s
\n",
     html.EscapeString(name.Name), html.EscapeString(constraint.String()))
   }
  }
  output.WriteString("
\n")
 }
 // 所有声明处理完才交付缓冲结果，避免中途失败留下半篇文档。
 fmt.Print(output.String())
}

输出带转义的文档记录

约束可能是命名接口、选择器或包含类型集合的接口字面量。格式化器展示的是语法写法，不会把别名或命名约束自动展开成完整的类型集合。文档应标成“约束声明”，避免让读者误以为这是已经展开后的语义结论。

代码对函数名、约束文字与注释都做 HTML 转义。注释是输入内容，直接拼进 HTML 可能改变页面结构；转义让它以文字展示。函数的 Doc 是整段函数说明，并不会自动分配给 A、B、K；需要逐参数说明时，应另行制定可解释的注释约定。

处理失败和语义信息的边界

解析错误与格式化错误应附带明确状态，不能悄悄跳过失败文件后交付一份看似完整的文档。示例先写输出缓冲，全部处理后才输出；生产任务可以保存失败文件路径与阶段，通知维护者修复同一输入，不需要修改函数声明来让文档生成通过。

示例排除了带 Recv 的方法，因为这里聚焦顶层泛型函数。泛型接收器方法所涉及的接收器类型参数不能用函数 TypeParams 的同一逻辑直接宣称覆盖。泛型类型声明则应读取 TypeSpec.TypeParams，属于另一种声明入口。

仅靠 AST 不能证明约束是否有效、同名符号指向哪个包或调用者能否满足约束。如果文档还需语义导航，可以增加 go/types 分析；但不能把“提取到了约束文字”说成“约束已通过检查”。本文不作性能收益承诺，选择 AST 是因为需要源码结构。

常见问题：nil TypeParams 是否报错？对普通函数是正常情况。可否按名称排序？不建议，文档应保留声明顺序。调用处的 int、string 去哪里找？那是类型实参，不是函数声明的类型参数，应单独分析实例化表达式。