想象一下公司里新来了一位助理，名叫“文森特”。他不写业务代码，却有一项特殊本领：任何人把自己抽屉里乱糟糟的旧代码丢给他，他都能在一杯咖啡的时间内，交回一份整洁的文档——每段代码是干什么的、参数怎么传、会抛什么异常、和哪个模块有依赖，写得清清楚楚。文森特的秘密说穿了并不神秘：他先快速翻阅代码的“骨架结构”，再用自己从海量程序设计语言书籍里练出的语言直觉，把代码“翻译”成人话。你不是也想要一个这样的文森特吗？这正是“代码文档自动生成”这门技术想做的事：让大语言模型当主笔，让代码结构分析当校对，二者配合，把开发者的维护负担大大减轻，让每一段代码都拥有配得上它的说明书。

岗位关联

学会代码文档自动生成，你就能理解 LLM 与语法分析如何协同作业，并能在实际研发流程中为遗留系统、SDK 接口与代码评审搭建自动化的文档流水线——这是代码智能工程师的必备基本功。

目录
  1. 可视化演示
  2. 文档生成概述
  3. 语言模型基础
  4. 摘要生成方法
  5. API描述提取
  6. 注释质量评估
  7. 可信度与一致性
  8. 基准与实验结果
  9. AI 应用场景
  10. Python 演示
  11. 常见误区
  12. 面试题

可视化演示

演示代码结构语义提取LLM摘要生成、API签名描述提取与注释质量评估、生成文档可信度验证与幻觉检测三大模式交互动画。

本节配有交互动效（进入视口后自动加载，约 3KB）。

代码摘要生成流程 源代码解析为AST提取函数名参数类型控制流语义 LLM将结构化语义信息转化为自然语言摘要描述 summary = LLM(AST(code)) 代码结构语义提取与LLM生成实现自动文档摘要

文档生成概述

文森特第一天上班时，只做了一件事：把公司里最没人愿意碰的“遗留系统”源码翻了一遍。三个小时后，他交出了一份《旧系统模块说明》，代码里哪些模块负责订单、哪些负责支付、哪些已经被废弃，一目了然。开发者们看完都愣了——这正是他们想要却一直没时间写的文档。文森特的做法听起来简单：先把整个代码库的结构摸清楚，再针对每段代码写说明。而这件事落到技术上，就是“代码文档自动生成”的完整闭环。

把文森特的工作流程拆开，你会看到三个环节：结构感知、内容生成、质量校验。结构感知对应代码本身的抽象语法树分析，相当于文森特先翻目录；内容生成对应大语言模型根据代码文本续写自然语言，相当于他把代码“翻译”成说明书；质量校验则负责判断生成的文档是否真实、是否完整。

在学术上，我们常把文档生成建模成这样一个最优化问题：在所有可能的文档候选中，选出在给定代码条件下概率最高的那一个。形式化写作：

文森特的工牌上其实就写着这个公式：结构分析告诉他“有哪些代码”，语言模型告诉他“该怎么说人话”。两者合一，就是那个让开发者拍手叫好的文档助理。

doc∗=arg⁡max⁡docP(doc∣code)\text{doc}^{*} = \arg\max_{\text{doc}} P(\text{doc} | \text{code})
这个公式的意思很直白：给定一段代码，模型把所有能想到的文档表述都“过一遍脑子”，最终挑选出它认为最顺理成章的那个版本。
  1. 候选文档doc 代表一个候选的文档文本，可能是“计算两数之和”，也可能是“把 a 和 b 加起来再返回”。
    doc\text{doc}
  2. 给定代码竖线后面的 code 表示条件，即所有推断都必须建立在代码内容的基础上，不能凭空编造。
    P(doc∣code)P(\text{doc} | \text{code})
  3. 取最大概率arg max 的含义是从候选集合中挑出概率最高的一项，作为最终输出。
    arg⁡max⁡doc\arg\max_{\text{doc}}

语言模型基础

文森特的桌上放着一本厚厚的速记本，上面全是他读过的开源项目笔记。他写文档时有个习惯：先看上一行写了什么，再决定下一行怎么写。比如他看到“def add(a, b):”，速记本就会告诉他，后面大概率跟“返回 a 加 b 的结果”。这不是什么魔法，而是他长期“读一句、猜下一句”训练出来的直觉。

大语言模型正是这样工作的。它把代码和文字都切成若干小片段（称为 token），然后训练自己根据已经看到的内容预测下一个片段。预测得越准，说明它对代码的理解越深。当程序员说“给我这个函数写注释”，模型就把函数代码当作已知的前文，用“接着写”的方式补出文档。

自回归语言模型的数学表达很简洁：整段文本出现的概率，等于每个词在给定前文条件下的概率连乘。设整段文本为 \(w_1, w_2, \ldots, w_T\)，则：

所以说，文森特的速记本并不神秘——它只是把亿万个“前文—后文”的配对压缩进了模型参数里。当他面对代码时，他不是在“背诵”，而是在“续写”。

P(w1,w2,…,wT)=∏t=1TP(wt∣w1,w2,…,wt−1)P(w_1, w_2, \ldots, w_T) = \prod_{t=1}^{T} P(w_t | w_1, w_2, \ldots, w_{t-1})
这个公式把“写文档”变成“做填空”：每填一个词，都要参考前面所有词。模型之所以能生成通顺的自然语言，正因为它擅长这种逐词续写。
  1. 序列展开左边表示整句话出现的联合概率，右侧用连乘符号把它拆成一步一步的条件概率。
    P(w1,w2,…,wT)P(w_1, w_2, \ldots, w_T)
  2. 条件概率右边每一项 \(P(w_t | w_1, \ldots, w_{t-1})\) 都是在“已知前文”的情况下预测下一个词。
    P(wt∣w1,w2,…,wt−1)P(w_t | w_1, w_2, \ldots, w_{t-1})
  3. 连乘组合\(\prod\) 表示把所有步骤的概率乘起来，一个词接一个词，最终得到整段文本的生成概率。
    ∏t=1T\prod_{t=1}^{T}

摘要生成方法

写一本书的封面折页，最考验功力：不能把书抄一遍，得用几句话说动人。文森特给整个项目写摘要时也是这样，他会先扫一遍目录（也就是代码的抽象语法树，简称 AST），看看有哪些模块、哪些函数，再挑出最重要的入口点，用三五行话概括项目“是干什么的”。

摘要生成分成两个层级：项目级摘要和函数级摘要。项目级摘要面向整个仓库，回答“这个代码库解决什么问题”；函数级摘要面向单个函数，回答“这个函数怎么用、注意什么”。前者需要模型有全局视野，后者需要模型精确捕捉局部逻辑。这时候，结构分析的价值就体现出来了——AST 能告诉模型哪些函数被调用最多、哪些是入口，模型据此把“注意力”放在更重要的代码片段上。

注意力机制是语言模型处理长代码时的核心工具。它让模型在生成“计算订单总额”这句话时，把大部分注意力集中在 calc_total 这个函数上，而不是去关注无关的辅助函数。注意力的计算方式如下：

文森特写摘要时，心里总有一张“重点清单”：入口函数排第一，被频繁调用的公共函数排第二，死代码直接忽略。注意力机制就是他心里的清单。

Attention(Q,K,V)=softmax(QK⊤dk)V\text{Attention}(Q, K, V) = \text{softmax}\left(\frac{QK^{\top}}{\sqrt{d_k}}\right)V
可以把 Q 想象成你正在写的问题：“这段代码在干什么？”K 是代码里每个片段的标签，V 是片段的具体内容。模型先看问题和哪个片段最对得上，再按对上的程度提取内容。
  1. 查询与键Q 是当前生成位置发出的查询，K 是所有代码片段的键，二者做点积来度量匹配程度。
    QK⊤QK^{\top}
  2. 缩放归一除以 \(\sqrt{d_k}\) 避免点积过大导致梯度问题，再经过 softmax 变成权重，总和为 1。
    softmax(QK⊤dk)\text{softmax}\left(\frac{QK^{\top}}{\sqrt{d_k}}\right)
  3. 加权汇总把权重作用到 V 上，得到注意力输出——也就是“模型最终关注的代码信息”。
    Attention(Q,K,V)\text{Attention}(Q, K, V)

API描述提取

如果你买了一套工具箱，最希望里面附带什么？当然是安装说明书——哪个扳手拧哪个螺丝，什么情况下会卡住。对开发者来说，每个函数就是一件工具，而 API 描述就是它的说明书。文森特整理 API 文档时，不会长篇大论，而是像写菜谱卡片一样：食材（参数）、成品（返回值）、翻车提示（异常）。

这些信息从哪里来？答案就藏在代码结构里。函数定义的参数列表、默认值、类型注解、return 语句、raise 语句，都是结构化信息；AST 遍历可以稳定地抽取它们。而大语言模型则负责把抽取的要素组织成通顺的自然语言。比如“参数 a: int, b: int, 返回 int”，模型会写成“接收两个整数参数并返回它们的和”。

参数类型识别在形式上看是一个分类问题：给定函数的特征向量 \(x\)，从候选类型集合中选出最可能的类型标签 \(y\)。其表达式为：

文森特整理 API 文档时有个习惯：每张菜谱卡片都留三栏——“用料”“成品”“容易翻车的地方”。参数、返回类型、异常说明，三项齐全，开发者照着做就不会出错。

y^=arg⁡max⁡y∈YP(y∣x)\hat{y} = \arg\max_{y \in \mathcal{Y}} P(y | x)
通俗地说，模型把函数签名当作线索（x），把“int、str、float、None”等类型当作候选答案（Y），然后选出它认为最可能的那个类型。
  1. 特征向量\(x\) 是由代码分析得到的特征，比如参数名、默认值、函数体内返回表达式的类型。
    xx
  2. 候选集合\(\mathcal{Y}\) 是所有可能的类型标签集合，相当于菜谱卡片上“食材种类”的全部候选项。
    Y\mathcal{Y}
  3. 后验概率\(P(y | x)\) 表示看到特征后认为类型是 \(y\) 的可信度，模型选择最大的一项。
    y^=arg⁡max⁡y∈YP(y∣x)\hat{y} = \arg\max_{y \in \mathcal{Y}} P(y | x)

注释质量评估

文森特有时会接到奇怪的任务：给前任程序员留下的注释打分。他发现，有的注释洋洋洒洒写了五行，却全是废话，比如“将 a 赋值给 b”——代码里一眼就能看出来的事；有的注释虽然只有三个词“防并发重复”，却精准地点出了问题的核心。这说明注释质量不能看字数，要看语义。

标准的注释质量评估方法，是让模型把注释和代码分别映射成语义向量，再计算两个向量的夹角余弦。如果注释很好地概括了代码功能，两条向量方向就会很接近；如果注释是应付了事的套话，向量方向就会偏到天边去。语义相似度被定义为：

给注释打分这件事，文森特从不只看“写没写”，而是问“写得对不对、说没说在点子上”。语义相似度替他完成了这层判断——字面不同但意思相同，是好注释；字面丰富但意思空洞，依然是差注释。

cos⁡(A,B)=A⋅B∥A∥⋅∥B∥\cos(A, B) = \frac{A \cdot B}{\|A\| \cdot \|B\|}
这个公式衡量两个语义向量的“默契程度”。A 是代码的向量表示，B 是注释的向量表示。夹角越小，说明注释越贴近代码的真实含义。
  1. 语义编码A 代表代码经模型编码后得到的向量，B 代表注释的编码向量。
    A,BA, B
  2. 点积聚合\(A \cdot B\) 将两个向量的对应维度相乘后求和，得到它们的关联强度。
    A⋅BA \cdot B
  3. 长度归一分母是两个向量模长的乘积，将结果压缩到 -1 到 1 之间，便于比较。
    A⋅B∥A∥⋅∥B∥\frac{A \cdot B}{\|A\| \cdot \|B\|}

可信度与一致性

最让开发者头疼的，不是文森特写不出文档，而是他偶尔会“一本正经地胡说八道”。他看到一段代码里有个 retry 参数，就大胆推断“这个函数会自动重试五次”，实际上代码只是把它传给下游，重试逻辑根本不在这个函数里。这种“编造事实”的现象，在 AI 领域叫作幻觉。

要对付幻觉，就得给文森特安排一个“验稿编辑”。编辑的工作很简单：把生成文档中的每一条信息，拿去和代码的真实行为比对。怎么比对？最直接的办法是运行测试：让文档描述的现象在真实执行中出现；另一个办法是将生成文档与人工维护的参考文档进行一致性对比。一致率可以量化成如下指标：

文森特能成为可靠的助理，不是因为他不犯错，而是因为他有“验稿编辑”把关。文档和代码行为对不上，就打回重写；对得上，才能盖章发布。

Acc=1N∑i=1NI[yi=y^i]\text{Acc} = \frac{1}{N} \sum_{i=1}^{N} \mathbb{I}[y_i = \hat{y}_i]
这里的逻辑和“对答案”一样：N 条文档断言里，有多少条与真实行为（或权威文档）吻合，吻合的比例就是一致率。如果一致率低，说明文森特在编故事，需要打回重写。
  1. 样本配对把生成文档拆成 N 条可验证的断言，例如“该函数重试 5 次”。
    NN
  2. 逐条判定\(\mathbb{I}[y_i = \hat{y}_i]\) 是指示函数，当第 i 条断言与真实行为一致时取 1，否则取 0。
    I[yi=y^i]\mathbb{I}[y_i = \hat{y}_i]
  3. 求平均前面乘 \(\frac{1}{N}\)、后面求和，得到 0 到 1 之间的一致率分数。
    1N∑i=1NI[yi=y^i]\frac{1}{N} \sum_{i=1}^{N} \mathbb{I}[y_i = \hat{y}_i]

基准与实验结果

为了检验文森特到底有几斤几两，公司决定办一场“文档写作大赛”：所有参赛的文档生成系统用同一批开源项目、同一套评分标准同场竞技。评分看两部分——内容的准确性用人工抽评，语言的流畅度用自动指标，比如 BLEU、ROUGE 或语义相似度。只有标准化，结果才有说服力。

评测流程通常遵循一个固定的范式：先在标准数据集上划分训练与测试，再让各系统在测试集上生成文档，最后用统一指标打分并与基线对比。所谓基线，往往是最朴素的模板方法或早期生成模型；比基线高，说明新技术有效。相对提升率的计算如下：

比赛结果证明：使用“大语言模型 + 结构分析”的组合，普遍比单纯用模板或单纯用模型的方案得分更高。文森特的成绩单贴在公告栏上，上面写着四个字：结构加持，文档更稳。

Δ=Mnew−MbaselineMbaseline×100%\Delta = \frac{M_{\text{new}} - M_{\text{baseline}}}{M_{\text{baseline}}} \times 100\%
这就好比文森特上一轮考了 60 分，这一轮考了 75 分，提升率就是 (75-60)/60=25%。百分比能让大家直观地看到“进步了多少”。
  1. 取两轮得分\(M_{\text{new}}\) 是新方法的评测得分，\(M_{\text{baseline}}\) 是基线方法的得分。
    Mnew,MbaselineM_{\text{new}}, M_{\text{baseline}}
  2. 求差分子上两者相减，得到绝对提升量。
    Mnew−MbaselineM_{\text{new}} - M_{\text{baseline}}
  3. 标准化的百分比除以基线得分并乘以 100%，得到便于跨任务比较的相对提升率。
    Mnew−MbaselineMbaseline×100%\frac{M_{\text{new}} - M_{\text{baseline}}}{M_{\text{baseline}}} \times 100\%

AI 应用场景

遗留系统文档补全

阶段：代码理解与分析

解决的问题：老系统的代码往往没有文档，新人入职只能靠“问老人”和“看代码”两条路，效率极低、知识易失。传统做法是组织人工逐模块阅读，成本高且容易过时。AI 可以自动扫描整个仓库，结合 AST 结构分析和大模型生成模块级与函数级文档，让新人在数小时内获得一份可用的项目向导。

具体案例：某银行核心系统有 20 年历史、约 200 万行 Java 代码，文档覆盖率不足 10%。开发团队用代码文档生成工具批量处理，一周内生成 1.2 万个函数的 Docstring 与 60 份模块说明，再由资深工程师抽查校对，最终文档覆盖率提升到 85%。

SDK 对外接口文档自动同步

阶段：文档生成与发布

解决的问题：对外 SDK 每次发版，参数变了、接口弃用了，手册却常常忘记更新，导致客户接入报错。传统的人工维护要跨版本、跨业务核对，工作量大且容易遗漏。AI 可以在 CI 流水线中自动提取 API 变更，生成对应更新说明，并标记不兼容变更，大幅缩短文档同步周期。

具体案例：某云厂商的 Python SDK 每周迭代，过去发布前需要文档工程师手动补写两天的更新日志。接入自动生成后，流水线在每次构建时自动产出版本间差异说明和参数对照表，人工只需花 30 分钟做最终确认，客户投诉明显下降。

代码评审中的注释质量门禁

阶段：质量评估

解决的问题：团队规范要求“核心函数必须写注释”，但评审人逐个检查效率低，且“写了但写错”的情况很难发现。AI 可以在 Pull Request 阶段自动评估注释质量与函数语义的一致性，将低质量注释标记出来，并给出修改建议，帮助团队把规则落到实处。

具体案例：某互联网公司后端仓库每月收到约 900 个 PR，此前注释规范完全靠人工提醒。引入自动质量门禁后，CI 会在提交时计算注释与函数的语义相似度，低于阈值的 PR 会被打回并要求补充说明，三个月后注释覆盖率从 55% 提升到 90%。

Python 演示

python40 行
import astfrom typing import List, Dict def infer_docstring(func: ast.FunctionDef) -> str:    args: List[str] = [a.arg for a in func.args.args]    ret: str = "无返回值"    if func.returns is not None:        if isinstance(func.returns, ast.Name):            ret = func.returns.id        elif isinstance(func.returns, ast.Attribute):            ret = func.returns.attr    desc = "实现" + func.name + "的功能逻辑。"    if args:        desc += "参数：" + "，".join(args) + "。"    desc += "返回类型：" + ret + "。"    return desc def process(source_code: str) -> List[Dict[str, str]]:    tree: ast.Module = ast.parse(source_code)    docs: List[Dict[str, str]] = []    for node in ast.walk(tree):        if isinstance(node, ast.FunctionDef):            item: Dict[str, str] = {                "函数": node.name,                "行号": str(node.lineno),                "文档": infer_docstring(node),            }            docs.append(item)    return docs if __name__ == "__main__":    source = '''def add(a: int, b: int) -> int:    return a + b def greet(name: str) -> str:    return "hello " + name'''    for item in process(source):        print(item["函数"], "第", item["行号"], "行")        print(item["文档"])
目的：这段代码演示了“结构分析 + 模板生成”的最简文档生成流水线——先用 AST 解析源码结构，再为每个函数提取参数与返回类型，最后组装成自然语言文档框架。
  1. tree: ast.Module = ast.parse(source_code)把源码字符串解析成抽象语法树，相当于文森特翻开代码的“目录”。
  2. for node in ast.walk(tree):深度优先遍历语法树中的每个节点，确保不漏掉任何一个函数角落。
  3. if isinstance(node, ast.FunctionDef):只挑出函数定义的节点，等于只关注“工具箱里的每件工具”。
  4. args = [a.arg for a in func.args.args]从函数节点中提取参数名列表，这是 API 文档里的“食材清单”。
  5. if isinstance(func.returns, ast.Name):判断返回类型是否为简单名称（如 int、str），是则直接取出类型名。
  6. desc = "实现" + func.name + "的功能逻辑。"用模板组织一段自然语言的主体描述，后续再拼接参数与返回信息。

常见误区

误区我总觉得只要每个函数都写了注释，哪怕都是“参数赋值给结果”这种废话，也算达标。毕竟数量上去了，总比没写强。

正解真正重要的是语义匹配度——注释是否准确、是否说明了代码没有自解释出来的关键信息。文森特打分时，一句“防并发重复”胜过十句“将 a 赋值给 b”。单纯增加无关注释，不仅不会提升质量，反而会增加阅读噪音。

为何常见：因为“覆盖率”是一个极易量化的指标，团队很容易把它当成 KPI。而语义质量需要模型判断，衡量成本更高，所以少有人深究。

误区模型那么厉害，生成的自然语言比人写的还通顺，应该可以直接推给用户看，省掉人工校对。

正解文森特也有“一本正经胡说八道”的时候。模型可能根据 retry 参数编造“自动重试五次”，但代码实际并没有这样做。生成文档必须经过可信度验证——用测试执行或人工对照检查关键断言，才能发布。

为何常见：因为模型的输出在语言层面太像真人，让人放松了对事实准确性的警惕。流畅不等于真实，这是 AI 幻觉带来的典型误判。

误区模型生成的文档和团队里老师傅写的文档只要句子不一样，就肯定是模型写错了，得逐字对照修改。

正解文档评价的是语义一致性，不是逐字拷贝。“返回两数之和”和“把 a、b 相加的结果返回”说明的是同一件事。只要事实断言一致、表达通顺即可，不必苛求字面相同。

为何常见：因为人习惯于用“原文比对”来检查作业，但这套逻辑用在语义丰富的文档上过于机械，忽略了自然语言的多样性。

误区模型能力这么强，直接把整个文件丢给它，它也能写出像样的文档，何必再做 AST 分析那么麻烦？

正解纯模型面对大型仓库时，容易忽略跨文件的调用关系、函数间依赖和异常路径；而结构分析为模型提供了“骨架地图”。二者结合才能在参数识别、异常枚举、调用链描述上做到完整准确。

为何常见：因为单看小函数的示例，模型的效果确实不错，让人误以为大模型可以包打一切；真实项目的复杂度会在规模效应下戳破这个幻觉。

面试题

Q1. 代码文档自动生成最核心的收益是什么？

单选题 · easy

  • A.减少开发者的维护负担← 正确答案
  • B.提高代码的执行速度
  • C.消灭所有程序运行 bug
  • D.替代编译器的优化功能

答案：A。文档自动生成的目标是把“写说明”这件繁琐事交给模型，让开发者把时间花在逻辑实现和系统设计上，因此核心收益是降低维护成本。它不改变代码执行路径，也不负责消灭 bug 或替代编译器。

Q2. 大语言模型生成文本的基本方式是什么？

单选题 · easy

  • A.逐字随机抽取字符
  • B.根据前文预测下一个词← 正确答案
  • C.完整复制已有代码库
  • D.查表匹配固定模板

答案：B。自回归语言模型的核心是条件概率：看到前文后再预测下一个 token，逐词生成完整文本。它不是随机抽取，也不是简单复制或查模板，而是基于大规模语料上学到的模式进行续写。

Q3. 给函数生成“参数说明、返回类型、异常说明”属于哪类任务？

单选题 · mid

  • A.项目级摘要生成
  • B.注释质量评估
  • C.代码风格格式化
  • D.API描述提取← 正确答案

答案：D。API 描述提取的特点是结构化：从函数签名中抽取参数名、默认值、返回注解与异常分支，再组织成说明书式的文字。摘要生成侧重整体概括，注释评估侧重事后打分，风格格式化与文档无关。

Q4. 以下哪些措施有助于减少生成文档的幻觉？

多选题 · mid

  • A.与人工参考文档做一致性比对← 正确答案
  • B.结合测试运行验证文档断言← 正确答案
  • C.让多个模型独立生成的结论互相印证← 正确答案
  • D.无限增长生成文本的长度

答案：ABC。一致性验证、运行时验证、多模型交叉印证都是检验“说法是否属实”的手段。而无限增长文本长度只能让模型写出更多字，并不提升事实准确率，甚至可能编出更多幻觉。

Q5. 为什么评估注释质量时，语义相似度比字面分词重合更可靠？

单选题 · hard

  • A.语义相似度计算速度更快
  • B.注释和代码本身语言不同，只能比语义← 正确答案
  • C.字面重合完全无法计算
  • D.词频统计比语义更主观

答案：B。代码是形式化语言，注释是自然语言，二者没有直接的 token 对应关系，必须通过嵌入映射到同一语义空间才能比较。语义相似度能识别“相加”与“求和运算是同义表达，而字面比对会把这两种合理写法误判为不匹配。

Q6. 在基准评测中，标准数据集的作用通常包含哪些？

多选题 · hard

  • A.划分统一的训练与测试集合← 正确答案
  • B.提供公开可比的任务难度← 正确答案
  • C.让不同系统按同一标准打分← 正确答案
  • D.自动修复生成文档中的所有错误

答案：ABC。标准数据集的核心价值是“同一把尺子量所有人”：统一的划分、统一的输入、统一的答案集，使论文结果可以横向对比。它不会修复文档错误，数据集的角色是考题而非判卷老师。判卷由评测指标来完成。

Q7. 项目级摘要和函数级摘要的关键区别是什么？

单选题 · mid

  • A.前者关注整个仓库的用途，后者关注单个函数的用法← 正确答案
  • B.前者用模板生成，后者用模型生成
  • C.前者不需要代码结构信息，后者必须运行测试
  • D.前者长度固定，后者长度无限

答案：A。项目级摘要面向仓库回答“解决什么问题”，函数级摘要面向单个函数回答“怎么使用”。两者都可能用到模板与模型，也都可能依赖结构信息，长度则随内容变化，没有固定限制。

Q8. 从 AST 中提取 API 描述信息时，raise 语句通常用来确定什么？

单选题 · mid

  • A.函数的参数默认值
  • B.函数可能抛出的异常类型← 正确答案
  • C.函数的返回类型注解
  • D.函数的装饰器数量

答案：B。raise 语句表示函数在特定条件下抛出异常，收集这些异常类型就能写出“可能抛出的异常”一栏。参数默认值来自参数节点的默认值字段，返回类型来自 return 和返回值注解，装饰器数量则与 API 用法说明无关。

Q9. 一致率指标 Acc = (1/N)Σ[y_i = ŷ_i] 中，指示函数的作用是什么？

单选题 · hard

  • A.将预测得分缩放到固定范围
  • B.统计单条断言是否与真实行为相符← 正确答案
  • C.计算模型生成文本的字数
  • D.衡量代码执行时间的快慢

答案：B。指示函数在断言成立时取值 1，不成立时取值 0，N 条断言累加再平均，得到“文档说法与真实行为的吻合比例”。它不会缩放分数、数数字数，也不关心执行时间。

Q10. 代码文档自动生成的典型技术输入有哪些？

多选题 · easy

  • A.抽象语法树等结构信息← 正确答案
  • B.大规模语言模型的先验知识← 正确答案
  • C.编译器的中间表示与运行行为← 正确答案
  • D.键盘录制的用户操作记录

答案：ABC。结构分析（AST）是骨架，大模型先验是语言组织能力，中间表示与运行行为能提供事实依据，三者都是文档生成的有效输入。键盘记录与代码文档没有关系，属于无关选项。