企业官网建设流程全解析

如何用Codo编写类与方法注释：@param、@option、@return注解实战

【免费下载链接】codocodo: Codo 是一个 CoffeeScript API 文档生成器，类似于 YARD，专注于 CoffeeScript 类语法的文档生成。项目地址: https://gitcode.com/gh_mirrors/cod/codo

Codo 是一个专注于 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 [Array<Animal>] 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 与 @throw

@return支持带类型和不带类型两种形式：

# 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 can't 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 can't be done # do: (it, again, options) ->

进阶注解：让文档更有"语义"

掌握三个核心注解后，再认识几个高频补充项：

自动链接是个隐藏福利：注释中提到已知的类名（如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