代码文档

Overview

在本指南中，您可以学习；了解Mongoid 的代码文档约定。 如果您有改进API文档或引入新功能的建议，可以使用本指南来帮助您格式化文档。

Mongoid 使用 YARD （一种Ruby文档工具）的变体来记录代码文档。

结构

• 模块：所有类和模块定义之前都必须有文档注释。

  # 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
  # must not be indented.
  #
  # @return [ Symbol ] For macros, wraps must be double-space indented
  #   on the second, third (and so on) lines.

• 空格：不要使用前导/尾随空注释行，也不要使用多个连续的空注释行。

  # DO THIS:
  # @return [ Symbol ] The return value
  def my_method
  # NOT THIS:
  # @return [ Symbol ] The return value
  #
  def my_method
  # NOT THIS:
  # @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 中不存在这种类型。

  # DO THIS:
  # @param [ true | false | nil ] bool A boolean or nil value.
  # NOT THIS:
  # @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' names as Strings.
  def buy_groceries(*items)

• Splat Args：不要使用Array作为类型，除非每个参数实际上是一个数组。

  # DO NOT DO THIS:
  # @param [ Array<String> ] *items The list of items' names as Strings.
  def buy_groceries(*items)
  buy_groceries("Cheese", "Crackers", "Wine")
  # DO THIS:
  # @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 or arguments.
  # @option opts [ String | Array<String> ] :items The items 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 or arguments.
  # @option **kwargs [ String | Array<String> ] :items The items 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

• 过程参数：对过程参数使用 @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