在JavaScript开发过程中，JSDoc注释是标注函数功能、参数类型、返回值信息的重要方式，很多时候我们需要从已有的函数中提取这些注释，用于自动生成文档、做静态代码分析或者实现自定义的开发工具功能。不同的提取需求对应不同的实现方案，下面介绍两种常用的提取方式。
方法一：基于正则表达式提取
如果提取场景比较简单，只需要获取函数上方紧邻的JSDoc注释，不需要处理复杂嵌套、多行注释拼接等情况，可以使用正则表达式快速实现。这种方式的优点是轻量、不需要引入额外的依赖库，适合小型工具或者简单的脚本场景。
实现思路
JSDoc注释的标准格式是以/**开头，以*/结尾的多行注释，通常位于函数声明的前面。我们可以通过正则表达式匹配函数定义前的JSDoc注释块，再提取其中的内容。
代码示例
// 待提取的目标函数代码
const funcCode = `
/**
* 计算两个数字的和
* @param {number} a 第一个加数
* @param {number} b 第二个加数
* @returns {number} 两个数字的和
*/
function add(a, b) {
return a + b;
}
/**
* 打印用户信息
* @param {string} name 用户名称
* @param {number} age 用户年龄
*/
function printUser(name, age) {
console.log(`姓名: ${name}, 年龄: ${age}`);
}
`;
// 匹配函数上方的JSDoc注释的正则表达式
// 匹配规则：以/**开头，中间任意非*/内容，以*/结尾，后面紧跟可选的空白字符和function关键字
const jsdocRegex = //**[sS]*?*/s*(?=functions+w+)/g;
// 提取所有匹配的JSDoc注释
const matches = funcCode.match(jsdocRegex);
if (matches) {
matches.forEach((comment, index) => {
console.log(`第${index + 1}个JSDoc注释内容：`);
console.log(comment);
console.log('---');
});
} else {
console.log('未找到匹配的JSDoc注释');
}
注意事项
- 该正则表达式只能匹配位于
function关键字前的JSDoc注释，如果函数是箭头函数、函数表达式，或者JSDoc注释和函数之间有其它代码，可能会出现匹配失败的情况。 - 如果代码中存在多个连续的JSDoc注释，或者注释中包含
*/字符串，正则匹配的结果可能会出现偏差。
方法二：基于AST抽象语法树提取
如果需要处理复杂的代码结构，比如箭头函数、函数表达式、类中的方法，或者需要精准关联注释和对应的函数节点，推荐基于AST的方式提取。这种方式通过解析JavaScript代码的语法结构，能够准确获取每个函数节点对应的前置注释，可靠性更高。
实现思路
我们可以使用acorn等JavaScript解析器将代码解析为AST，然后遍历AST节点，找到所有的函数类型节点，再获取这些节点前面的注释节点，筛选出符合JSDoc格式的注释即可。这种方式需要先安装acorn和acorn-walk依赖。
代码示例
// 先安装依赖：npm install acorn acorn-walk
const acorn = require('acorn');
const walk = require('acorn-walk');
// 待解析的函数代码
const code = `
/**
* 计算两个数字的和
* @param {number} a 第一个加数
* @param {number} b 第二个加数
* @returns {number} 两个数字的和
*/
function add(a, b) {
return a + b;
}
const multiply = (x, y) => {
return x * y;
};
class User {
/**
* 创建用户实例
* @param {string} name 用户名称
*/
constructor(name) {
this.name = name;
}
}
`;
// 解析代码为AST，开启位置和注释收集选项
const ast = acorn.parse(code, {
ecmaVersion: 2020,
locations: true,
onComment: (block, text, start, end) => {
// 收集所有注释，把注释信息存到全局数组中
if (!ast.comments) ast.comments = [];
ast.comments.push({
block,
text,
start,
end
});
}
});
// 遍历AST，找到所有函数相关节点
const functionNodes = [];
walk.simple(ast, {
FunctionDeclaration(node) {
functionNodes.push(node);
},
FunctionExpression(node) {
functionNodes.push(node);
},
ArrowFunctionExpression(node) {
functionNodes.push(node);
}
});
// 关联注释和函数节点，提取JSDoc注释
functionNodes.forEach(node => {
// 获取函数节点的起始位置
const funcStart = node.start;
// 找到函数前面最近的注释
const prevComment = ast.comments
.filter(comment => comment.end <= funcStart)
.sort((a, b) => b.end - a.end)[0];
if (prevComment && prevComment.block && prevComment.text.startsWith('*')) {
console.log('找到函数对应的JSDoc注释：');
console.log(`/*${prevComment.text}*/`);
console.log('---');
}
});
优势说明
- 支持所有函数类型，包括函数声明、函数表达式、箭头函数、类方法等。
- 能够精准匹配函数和对应注释的位置关系，不会受到代码顺序混乱的影响。
- 可以扩展实现注释内容的解析，比如提取
@param、@returns等标签的具体信息。
两种方法的场景选择
如果是简单的脚本、一次性处理少量规则代码，优先选择正则表达式方式，开发成本低。如果是开发通用工具、需要处理复杂项目代码、要求提取结果准确，优先选择AST方式，虽然需要引入依赖，但稳定性和扩展性更好。
实际开发中如果需要更完善的JSDoc解析能力，也可以使用专门的JSDoc解析库，比如jsdoc-api，这些库已经封装了AST解析和注释提取的逻辑，使用起来更加便捷。
JavaScriptJSDocAST函数注释提取正则表达式修改时间：2026-06-26 05:03:42