Notion AI可自动生成代码注释，需在代码块内选中函数后点击“⋯→Ask AI”并输入格式化指令，或用/ai块、数据库AI属性、@关联文档、/ask ai多轮交互等方式触发。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在Notion中编写代码块（如Python、JavaScript等），但希望AI自动生成规范的函数说明与参数描述注释，却未掌握触发方式或指令结构，则可能是由于未在正确上下文中调用AI，或未提供足够语义线索供模型识别函数签名。以下是实现Notion AI自动写代码注释的具体操作步骤：
一、在代码块内直接调用AI生成注释
此方法适用于已粘贴或手写完成的函数代码，通过选中代码并激活AI，使其基于语法结构与上下文推断功能意图与参数含义。
1、在Notion页面中插入代码块：输入/code，选择对应语言（如Python），粘贴含函数定义的代码段。
2、用鼠标完整选中该函数代码（包括def行、参数列表、冒号及后续缩进逻辑块）。
3、点击右侧浮现的“⋯”按钮，选择Ask AI。
4、在AI对话框中输入指令：为该函数生成符合Google Python Style Guide的docstring，包含函数功能说明、Args参数列表（含类型与用途）、Returns返回值说明。
5、点击Send，AI将返回结构化注释文本；手动将其插入至函数定义下方第一行，并确保缩进与代码对齐。
二、使用/ai命令块配合代码截图或描述触发
当代码尚未粘贴至Notion，或仅存伪代码/自然语言描述时，可通过独立AI块输入结构化提示，驱动AI反向生成带注释的完整函数。
1、在页面空白处输入/ai，回车创建AI命令块。
2、输入指令：根据以下需求生成Python函数及完整docstring：函数名为calculate_discounted_price，接收price（float）、discount_rate（float，0.0–1.0）、tax_rate（float）三个参数，返回含税折后价（float）。docstring须按NumPy风格书写，分Section标注Parameters与Returns。
3、按下回车，AI输出含函数定义与标准注释的代码块。
4、将结果复制至目标代码块中，或点击Insert直接嵌入当前光标位置。
三、在数据库中批量为代码片段生成标准化注释
适用于维护多个算法函数、工具方法的代码资产库，通过Database关联AI属性，实现一次配置、多行同步生成统一风格的注释模板。
1、创建一个Database，添加字段：Name（文本）、Code_Snippet（文本）、Language（选择项：Python/JS/TS等）、Auto_Comment（AI属性）。
2、点击Auto_Comment列任意单元格，输入/ai，再键入：基于Code_Snippet和Language字段，为该函数生成兼容JSDoc（JS/TS）或Sphinx（Python）格式的注释，明确列出每个参数名、类型、默认值（若存在）及作用。
3、保存后，该行Auto_Comment字段即显示生成结果；修改Code_Snippet后，右键该字段选择Regenerate可刷新注释。
4、导出为Markdown或PDF时，注释与代码自动并置，满足文档交付要求。
四、利用@关联外部技术文档增强注释准确性
当函数涉及特定协议、API或领域模型时，AI可能因缺乏上下文而误判参数语义。通过@引用已有技术说明页，可显著提升注释的专业性与一致性。
1、提前在Notion中创建一页，标题为“支付网关参数规范”，内容列出payment_method、currency_code等字段的业务定义与约束。
2、在需注释的代码块所在页面，输入/ai，然后在指令中嵌入：参考@支付网关参数规范，为process_payment函数生成注释，特别说明payment_method参数必须为['alipay','wechat','card']之一，currency_code需符合ISO 4217标准。
3、AI将融合引用页内容生成精准注释，避免通用化描述偏差。
五、通过聊天式多轮交互精炼注释粒度
初始生成的注释可能过于简略或冗余，利用/ask ai开启持续对话窗口，可逐层细化参数说明、补充异常场景或调整术语层级。
1、在页面中输入/ask ai并回车，打开独立AI对话面板。
2、首轮输入：为以下fetchUserData函数生成TypeScript JSDoc注释：async function fetchUserData(id: string): Promise<User>。
3、AI返回基础注释后，在同一窗口追加指令：补充@throws部分，说明当id为空字符串时抛出InvalidIDError，HTTP 404时抛出UserNotFoundError。
4、再次追加：将所有参数说明改为中文，但保留类型标注（如string、Promise<User>）不变。
