代码文档
代码文档
Mongoid 使用自己的 YARD 风格 以获取代码文档。请注意本文档中概述的约定。
结构
模块:所有类和模块定义之前都应有文档注释。
# This is the documentation for the class. It's amazing # what they do with corrugated cardboard these days. class CardboardBox 方法:所有方法定义之前都应有文档注释。 使用
@param
、@yield
和@return
指定输入和输出。 有关更多详细信息,请参阅下面的类型声明。# Turn a person into whatever they'd like to be. # # @param [ Person ] person The human to transmogrify. # # @return [ Tiger ] The transmogrified result. def transmogrify(person) 错误:使用
@raise
解释特定于该方法的错误。# @raise [ Errors::Validations ] If validation failed. def validate! 私有方法:除非私有方法非常简短明了,其用途显而易见,否则应记录私有方法。 请注意,示例,方法可能简短明了,但其参数的类型可能不明显,在这种情况下,必须适当记录参数。
private # Documentation is optional here. def do_something_obvious 私有 API:不适合外部使用的类和公共方法应标记为
@api private
。 该宏不需要注释。请注意,由于 Mongoid 的模块混合到应用程序类中,因此方法的
private
可见性并不一定表明其为 API 私有方法。# This is an internal-only method. # # @api private def dont_call_me_from_outside 注释和 TODO:使用
@note
来解释注意事项、边缘情况以及可能令用户感到惊讶的行为。 使用@todo
记录后续改进的后续行动和建议。# Clear all stored data. # # @note This operation deletes data in the database. # @todo Refactor this method for performance. def erase_data! 弃用:使用
@deprecated
宏指示已弃用的功能。 该宏不需要注释。# This is how we did things back in the day. # # @deprecated def the_old_way
格式化
换行:在宏换行时使用双倍行距缩进。 请勿在描述中缩进换行。
# This is the description of the method. Line wraps in the description # should not be indented. # # @return [ Symbol ] For macros, wraps must be double-space indented # on the second, third, etc. lines. 空格:不要使用前导/尾随空注释行,也不要使用多个连续的空注释行。
# GOOD: # @return [ Symbol ] The return value def my_method # BAD: # @return [ Symbol ] The return value # def my_method # BAD: # @param [ Symbol ] foo The input value # # # @return [ Symbol ] The return value def my_method(foo)
类型声明
类型联合:使用管
|
表示允许类型的联合。# @param [ Symbol | String ] name Either a Symbol or a String. 嵌套类型:使用尖括号
< >
表示类型嵌套。# @param [ Array<Symbol> ] array An Array of symbols. 哈希:使用逗号
,
表示键和值类型。# @param [ Hash<Symbol, Integer> ] hash A Hash whose keys are Symbols, # and whose values are Integers. 数组:使用管
|
表示允许类型的联合。# @param [ Array<Symbol | String> ] array An Array whose members must # be either Symbols or Strings. 数组:使用逗号
,
表示元组中每个位置的类型。# @return [ Array<Symbol, Integer, Integer> ] A 3-member Array whose first # element is a Symbol, and whose second and third elements are Integers. 数组:如果内部类型不能在数组中混合,请在顶层使用管道
|
。# @param [ Array<Symbol> | Array<Hash> ] array An Array containing only # Symbols, or an Array containing only Hashes. The Array may not contain # a mix of Symbols and Hashes. 嵌套类型:为清楚起见,当同时使用逗号时,请使用方括号
[ ]
表示嵌套联合。# @param [ Hash<Symbol, [ true | false ]> ] hash A Hash whose keys are Symbols, # and whose values are boolean values. Ruby 值:可以使用 Ruby 语法在类型中表示特定值。
# @param [ :before | :after ] timing One of the Symbol values :before or :after. True、False 和 Nil:使用
true
、false
和nil
而不是TrueClass
、FalseClass
和NilClass
。 请勿将Boolean
用作类型,因为 Ruby 中不存在这种类型。# GOOD: # @param [ true | false | nil ] bool A boolean or nil value. # BAD: # @param [ TrueClass | FalseClass | NilClass ] bool A boolean or nil value. # @param [ Boolean ] bool A boolean value. 返回自身:
self
当方法返回 时,指定返回值self
。# @return [ self ] Returns the object itself. Splat 参数:在类型声明中使用三点省略号
...
并在参数名称中使用星*
来表示 splat。# @param [ String... ] *items The list of items name(s) as Strings. def buy_groceries(*items) Splat Args:不要使用
Array
作为类型,除非每个参数实际上是一个数组。# BAD: # @param [ Array<String> ] *items The list of items name(s) as Strings. def buy_groceries(*items) buy_groceries("Cheese", "Crackers", "Wine") # OK: # @param [ Array<String>... ] *arrays One or more arrays containing name parts. def set_people_names(*arrays) set_people_names(["Harlan", "Sanders"], ["Jane", "K", ""Doe"], ["Jim", "Beam"]) splat参数:使用逗号
,
表示 splat 中的位置。# @param [ Symbol..., Hash ] *args A list of names, followed by a hash # as the optional last arg. def say_hello(*args) Splat Args:用方括号
[ ]
指定类型联合。# @param [ [ String | Symbol ]... ] *fields A splat of mixed Symbols and Strings. 关键字参数:按照 YARD 约定,使用
@param
作为关键字参数,并将关键字参数名称指定为符号。# @param [ String ] query The search string # @param [ Boolean ] :exact_match Whether to do an exact match # @param [ Integer ] :results_per_page Number of results def search(query, exact_match: false, results_per_page: 10) 哈希选项:紧随哈希
@param
后使用@option
宏定义哈希键值选项。 注意@option
参数名称是符号。# @param opts [ Hash<Symbol, Object> ] The optional hash argument(s). # @option opts [ String | Array<String> ] :items The items(s) as Strings to include. # @option opts [ Integer ] :limit An Integer denoting the limit. def buy_groceries(opts = {}) Double Splats:在参数名称中使用双星
**
来表示关键字 arg splat (double splat)。 请注意,无需在 double-splat 元素上声明 type,因为它隐式为 <Symbol, 对象>。相反,请使用下面的@option
宏定义值类型。 注意@option
参数名称是符号。# @param **kwargs The optional keyword argument(s). # @option **kwargs [ String | Array<String> ] :items The items(s) as Strings to include. # @option **kwargs [ Integer ] :limit An Integer denoting the limit. def buy_groceries(**kwargs) 块:使用
@yield
指定该方法何时生成区块。# @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime. # Must take the person, location, and weapon used. Must return true or false. def whodunit yield(:mustard, :ballroom, :candlestick) end 块:如果该方法显式指定区块参数,请使用
@param
指定区块参数,前面加上与符号&
,并指定@yield
。 请注意,即使方法在内部调用block.call
而不是yield
,也应使用@yield
。# @param &block The block. # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime. # Must take the person, location, and weapon used. Must return true or false. def whodunit(&block) yield(:scarlet, :library, :rope) end # @param &block The block. # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime. # Must take the person, location, and weapon used. Must return true or false. def whodunit(&block) block.call(:plum, :kitchen, :pipe) end 块:使用
@yieldparam
和@yieldreturn
代替@yield
,以保持清晰。# @param &block The block. # @yieldparam [ Symbol ] The person. # @yieldparam [ Symbol ] The location. # @yieldparam [ Symbol ] The weapon used. # @yieldreturn [ true | false ] Whether the guess is correct. def whodunit(&block) yield(:peacock, :conservatory, :wrench) end Proc Args: Proc 参数应使用
@param
(而不是@yield
)。 可以将过程的输入指定为子类型。# @param [ Proc<Integer, Integer, Integer> ] my_proc Proc argument which must # take 3 integers and must return true or false whether the guess is valid. def guess_three(my_proc) my_proc.call(42, 7, 88) end