如何用Codo编写类与方法注释param、option、return注解实战【免费下载链接】codocodo: Codo 是一个 CoffeeScript API 文档生成器类似于 YARD专注于 CoffeeScript 类语法的文档生成。项目地址: https://gitcode.com/gh_mirrors/cod/codoCodo 是一个专注于 CoffeeScript 的 API 文档生成器思路类似 Ruby 社区的 YARD你只需要在类的注释里写上param、option、return等注解运行codo命令就能自动生成可浏览、可搜索的完整文档站点。本文通过真实示例手把手带你掌握 Codo 类与方法注释的写法快速上手最核心的三个注解。先认识 Codo一个命令生成整个文档站Codo 会递归扫描目录里所有 CoffeeScript 文件自动识别类、方法、常量、混入mixin和关注点concern并生成带导航和模糊搜索按T键触发的站点。安装后你只需要一条命令npm install -g codo codo src/它的核心工作流是三步写注解 → 跑命令 → 生成站点。注解语法全部集中在解析器 lib/documentation.coffee 中实现官方 README 的 Tags 章节给出了完整的注解清单。类级注释给整个类加上下文类注释写在类定义的正上方Codo 会自动识别。以项目自带示例 spec/_templates/example/src/angry_animal.coffee 为参考# Base class for all animals. # # example How to subclass an animal # class Lion extends Animal # move: (direction, speed): - # class Example.Animal几个常用类级注解namespace— 指定命名空间mixin— 把普通对象标记为混入对象Codo 会生成独立的混入页面include/extend— 声明混入关系混入方法会自动出现在类文档中abstract— 标记抽象类example— 后面紧跟缩进两格的代码块作为使用示例展示在文档里方法注释核心param 注解的两种写法Codo 的param支持两种等价写法选你顺手的即可解析规则见 lib/documentation.coffee写法一类型在前# Move the animal. # # param [Object] options the moving options # move: (options {}) -写法二参数名在前# Move the animal. # # param options [Object] the moving options # move: (options {}) -几个实战细节类型支持多选param [String, Char] input用逗号分隔即可数组泛型return [ArrayAnimal] the animals in the herd花括号语法如果你习惯 JSDoc 风格方括号可换成花括号如param {String} it命名参数自动识别constructor: ({name, phone, picture}) -这种解构写法会被 Codo 自动拆分成独立参数逐个标注即可参考 spec/_templates/methods/named_parameters.coffee描述对象参数内部option 注解当方法接收一个配置对象时option能把对象的每个字段单独列出来这是写配置项清单的关键# Feed the animal # # param [Object] options the feeding options # option options [String] time the time to feed # option options [Number] amount the amount of food # feed: (options) -注意option的第一个词必须是参数名这里是options它把所有选项归组到对应的参数下面最终在文档中渲染成一张字段表格。描述返回值与异常return 与 throwreturn支持带类型和不带类型两种形式# Get the distance in a certain time. # # param [Integer] time Number of seconds # return [Integer] The distance in miles # distance: (time) -配合throw可以说明可能抛出的错误# param [String] it The thing to do # return [Boolean] When successful executed # throw [TypeError] when it cant be done do: (it) -一个更完整的实战模板可直接照抄来源spec/_templates/methods/method_documentation.coffee# Do it! # # see #undo for more information # # param [String] it The thing to do # param again [Boolean] Do it again # param [Object] options The do options # option options [String] speed The speed # option options [Number] repeat How many times to repeat # return [Boolean] When successful executed # throw [TypeError] when it cant be done # do: (it, again, options) -进阶注解让文档更有语义掌握三个核心注解后再认识几个高频补充项注解用途适用场景example嵌入使用示例代码块类、混入、方法see引用其他类/方法/URL自动加链接通用overload声明方法的多种签名参数可变的泛用方法method文档中展示虚拟方法动态挂载的方法property标注实例变量的类型类成员变量deprecated标记废弃并给出提示通用private/nodoc隐藏方法或整个类通用todo/note留下备忘与备注通用自动链接是个隐藏福利注释中提到已知的类名如Animal.Lion会被自动解析成站内链接无需手写 Markdown 链接。生成文档与项目配置技巧生成文档时可以自定义输出常用选项codo src/ -o ./doc -n My Project --title My Project Documentation项目级默认配置可以写进.codoopts文件把选项逐行写好后跑codo无需任何参数--name Codo --readme README.md --output ./doc --min-coverage 80 ./src其中--min-coverage非常实用设定最低文档覆盖率未达标时构建直接失败非常适合放进 CI 保障注释质量。常见错误清单注解写不进去缩进不对example、overload、method等标签后面的代码块必须缩进两格option少了参数名漏掉第一个词会导致选项无法归组param名称与真实参数对不上Codo 会把已知类型自动链接但参数名仍需与方法签名保持一致注释紧贴代码建议以空行注释#单独一行分隔描述区和标签区解析更稳定总结Codo 的注释体系其实很克制类注释定框架param说入参option拆配置return说结果再加上example和see补充上下文就足以生成一份专业的 API 文档站。所有示例都可参考 spec/_templates/methods/ 目录下的模板文件想深入标签解析细节直接阅读 lib/documentation.coffee 即可。【免费下载链接】codocodo: Codo 是一个 CoffeeScript API 文档生成器类似于 YARD专注于 CoffeeScript 类语法的文档生成。项目地址: https://gitcode.com/gh_mirrors/cod/codo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考