使用 YARD 将参数标记为可选（或具有默认值）答案

【问题标题】：Mark a parameter as optional (or has a default) with YARD使用 YARD 将参数标记为可选（或具有默认值）
【发布时间】：2011-10-21 16:47:39
【问题描述】：

我正在使用 YARD 来记录我的代码。我有一个方法，它有一个带有默认值的可选参数。如何说明该参数是可选的并且具有默认值？

例子：

# Squares a number
# 
# @param the number to square
def square_a_number(number = 2)
  number * number
end

【问题讨论】：

标签： ruby yard

【解决方案1】：

YARD 现在自动支持参数默认值。

YARD 根据方法定义自动计算出默认值。瑞典语！

例如下面的代码文档会产生后续的 YARD doc：

# Squares a number.
# 
# @param number [Integer] The number to square.
#
def square_a_number(number = 2)
  number * number
end

Parameters:
  number (Integer optional) (defaults to: 2)

【讨论】：

如果您使用 contracts gem 之类的东西来强制执行必需或可选参数，那么自动推理将无济于事。如果 YARD 允许在这里明确说明就好了。
@AbeVoelker 我没有使用过 Contracts gem，但据我所知，它强制执行参数的预期 type，而不是它们是可选的还是必需的，还是由方法参数中是否赋值来处理的。
我确实使用它，并且there is a KeywordArgs contract which allows nested Optional contract 输入。示例：github.com/abevoelker/scrapinghub/blob/…
@AbeVoelker 啊，我明白了，所以在定义Hash 类型的必需方法参数的情况下，例如def list(args)，并且args 中的一些键是必需的，而一些是可选的。
@AbeVoelker 在这种情况下，您可以使用@!method 提供包含默认值的签名，并且将从中读取默认值，就像它在代码中的def <method-name> 中一样。

【解决方案2】：

要标记参数是选项，您可以简单地使用@param optional（请参阅http://rubydoc.info/docs/yard/file/docs/Tags.md）。据我所知，现在有一种方法可以标注默认值；您可能最好将其放在描述中（“平方数，默认为 2”）

【讨论】：

我不认为这是文档中的一个选项，并且我尝试添加 optional 的所有排列导致字符串“可选”被添加到各个地方的输出中，而没有任何特殊格式。也许我遗漏了一些东西，但这似乎不受支持？
也许另一个答案应该是公认的答案，因为它确实支持基于方法参数定义