开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载在生成 TypeScript 项目的 API 文档时文件头部的Copyright、许可条款声明如 Apache-2.0通常不应出现在最终的文档站点中——它们属于法律文本而非 API 说明。TypeDoc 提供了license块级标签Block Tag来声明这一点任何包含license的注释都会被自动排除不会出现在生成的文档里。阅读本文后你将掌握license的完整用法、它与其他排除型标签如import的关系以及 TypeDoc 注释解析管线中实现该机制的源码级细节从而在项目中正确组织文档注释而不产生意外输出。一、基本用法与官方示例license是一个块级标签Block Tag分类见 标签总览。其官方文档site/tags/license.md给出的行为描述非常简洁license标签用于声明一段不应出现在文档中的许可注释。任何包含license的注释都会被排除在生成文档之外。最典型的用法是在导出的 API 声明上方写一个仅含许可声明的 JSDoc 块/** license Apache-2.0 */ export const api {...} // not documented在这个示例中api上方的注释只承载许可信息TypeDoc 检测到license后不会将其解析为该符号的文档注释因此api在文档中表现为无文档而非显示一段许可文本。需要强调的是行为粒度排除的是整条注释而不是标签本身。一条注释只要含有license它的摘要summary、正文和其他标签内容都不会进入文档。二、源码级机制license在哪里被拦截license的效果由 TypeDoc 的注释解析管线实现核心代码位于 src/lib/converter/comments/index.ts。该文件是所有注释发现 → 词法分析 → 解析 → 缓存流程的入口license的过滤发生在解析完成之后的两个关键位置1. 符号级注释getCommentImpl当一个声明函数、变量、类等准备绑定文档注释时getCommentImpl会检查解析结果// src/lib/converter/comments/index.ts (约 L141) if (comment?.getTag(import) || comment?.getTag(license)) { return; }这里返回undefined意味着整条注释对该符号不可见——既不作为文档注释也不会产生摘要。注意它与importTypeScript 5.5 引入的 JS 类型导入标签见 site/tags/import.md共用同一拦截逻辑两者都属于合法存在于注释中、但不应成为文档内容的标签。2. 文件级注释getFileComment文件头注释模块注释走getFileComment路径。它逐个遍历发现的注释在安静上下文不写缓存、不打印警告中先行解析再判断// src/lib/converter/comments/index.ts (约 L259) if (comment?.getTag(license) || comment?.getTag(import)) { continue; } if ( comment?.getTag(module) || comment?.hasModifier(packageDocumentation) ) { return getCommentWithCache(commentSource, context); } return;这段逻辑还揭示了一个重要的配套规则文件注释要成为模块文档必须带有module标签或packageDocumentation修饰符否则它会被视为属于文件内第一条语句直接丢弃。从源码结构看license注释在这里被continue跳过而非直接终止意味着如果一个文件头部同时存在许可注释和模块文档注释解析会继续寻找有效的模块注释。3. 标签注册表license之所以能被getTag(license)精确识别是因为它被注册在 TypeDoc 的块级标签列表中——见 src/lib/utils/options/tsdoc-defaults.ts 第 32 行的blockTags数组。该列表同时注释要求更新tsdoc.json以保持同步。另外在中文本地化词表中license有对应的显示名许可协议见 src/lib/internationalization/locales/zh.ts用于诊断信息中的标签命名。三、真实仓库中的测试用例gh2552TypeDoc 仓库自带一个针对该行为的回归测试对应 GitHub issue #2552忽略license与import注释测试输入文件为 src/test/converter2/issues/gh2552.js/** * Summary * license MIT * * Full permission notice. */ // TS 5.5 import comments /** import ts from typescript */ /** * This is an awesome module. * module good-module */ /** import ts2 from typescript */ export const something 1;这个测试文件刻意覆盖了三个场景一条同时含有摘要文本Summary、Full permission notice.和license MIT的注释——验证整个注释被排除而不是只去掉标签行文件头部连续出现license注释、import注释和带module的模块注释——验证解析器跳过前两者后仍能找到真正的模块文档导出变量something上方只有import注释——验证该变量最终没有文档注释。对应的断言在 src/test/issues.c2.test.ts 中it(#2552 Ignores license and import comments, , () { const project convert(); equal( Comment.combineDisplayParts(project.comment?.summary), This is an awesome module., ); equal(getComment(project, something), ); });即项目级注释的摘要应恰好是module good-module那条注释的内容而something的注释为空。运行pnpm test测试入口见src/test/issues.c2.test.ts可以复现这一验证。四、使用建议与边界情况结合文档与源码可以归纳出几条实战要点整条注释都会消失。不要把真正的 API 摘要和license写在同一条 JSDoc 里gh2552 用例中 Summary 也一并被排除。正确做法是拆成两条注释或把许可声明单独放在文件顶部。文件头部许可头。若你习惯在文件首行放置Copyright ... license MIT形式的头注释TypeDoc 会直接跳过它模块文档请另行通过module或packageDocumentation声明二者互不干扰。与import同机制。importTS 5.5 起用于.js文件的 JSDoc 类型导入参考 site/tags/import.md与license在源码中走同一行拦截逻辑任何含import的注释同样不会进入文档。仅影响注释归属不影响排除策略配置。需要更细粒度的哪些成员不进文档控制时可配合excludeNotDocumented、excludeCategories等选项见 site/options/validation.md 与 site/options/organization.mdlicense专门解决的是注释存在但内容不是文档这一类场景。五、小结license是 TypeDoc 中成本极低、收益明确的块级标签一行注释即可让许可声明从文档管线中彻底隐身。其实现位于注释解析的统一入口 src/lib/converter/comments/index.ts通过getCommentImpl与getFileComment两处对getTag(license)的检查完成拦截并有 src/test/converter2/issues/gh2552.js 作为回归保障。在组织项目文档注释时将许可文本与 API 文本分置不同注释块再交由license自动排除是保持生成文档干净的可靠方式。赞分享开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载相关推荐TypeDoc {inheritDoc} 标签详解从其他声明复制与继承文档注释TypeDoc {inheritDoc} 标签详解从其他声明复制与继承文档注释 inheritDoc 是 TypeDoc 注释标签体系中用于文档复用的开发工具文档TypeDoc function 标签详解把可调用的变量声明转换为函数文档TypeDoc function 标签详解把可调用的变量声明转换为函数文档 TypeDoc 的 function 标签属于修饰符Modifier标签开发工具文档TypeDoc 标签体系详解TypeScript 项目文档注释中的 Block、Modifier 与 Inline 标签TypeDoc 标签体系详解TypeScript 项目文档注释中的 Block、Modifier 与 Inline 标签 TypeDoc 允许开发者在 JSD开发工具文档上一篇解决大型图片裁剪卡顿Cropper.js性能优化实战指南下一篇终极指南bootstrap-datepicker版本迁移中的API变更与适配技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考