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

Question

我正在使用YARD来文档化我的代码。 我有一个带有默认值的可选参数方法。 如何注明该参数是可选的且具有默认值？

示例:

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

- brainimus

---

YARD现在自动支持Param Defaults。我添加了一个答案，以帮助新手着陆此处。 - Joshua Pinter

Answer 1

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

YARD会根据方法定义自动确定默认值。瑞典语！

例如，下面的代码文档将生成相应的YARD文档：

代码文档

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

生成的 YARD 文档

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

- Joshua Pinter

---

如果您正在使用像contracts gem这样的工具来强制执行必需或可选参数，则自动推断是无效的。如果YARD允许在此处明确说明将会很好。 - Abe Voelker

@AbeVoelker 我没有使用过Contracts gem，但据我所知，它强制执行参数的期望“类型”，而不是它们是否可选或必需的，这仍由方法参数中的值是否被分配来处理。 - Joshua Pinter

我确实使用它，并且有一个KeywordArgs合同，允许嵌套的Optional合同类型。例如：https://github.com/abevoelker/scrapinghub/blob/cbdb9735e6203915e0133e4896f592bfd4e5d1cd/lib/scrapinghub/jobs.rb - Abe Voelker

您IP地址为143.198.54.68，由于运营成本限制，当前对于免费用户的使用频率限制为每个IP每72小时10次对话，如需解除限制，请点击左下角设置图标按钮（手机用户先点击左上角菜单按钮）。 - Joshua Pinter

@AbeVoelker 您可以使用 @!method 来提供一个包含默认值的签名，这种情况下，默认值将从该签名中读取，就像它在代码中的 def <method-name> 中一样。 - Steve Jorgensen

Answer 2

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

- Alex Peattie

---

我在文档中没有看到这个选项，而且我尝试了各种添加“optional”的排列组合，结果输出的字符串中都会以不同的方式添加“optional”，但没有任何特殊格式。也许我漏掉了什么，但似乎不支持这个选项？ - eprothro

也许另一个答案应该被接受，因为它根据方法参数定义提供了支持。 - msanjay