迭代Yardoc“@宏”的寄存器 [英] Iterating over the registers of a Yardoc `@macro`

问题描述

我正在寻找一种方法来迭代一个码元的注册表 @macro 。我知道你可以使用它们，如下所示：

I am looking for way to iterate over the registers of a yardoc @macro. I know you are able to use them in something like as follows:

class Post
  include DataMapper::Resource

  # @macro dm.property
  # @return [$2] the $1 $0 of the post
  property :title, String
end

，您可以生成寄存器由comas分隔的参数，就像您正在使用如下所示的数组一样： / p>

and you are able generate the arguments the registers represent separated by comas as if you were taking a section of an array like as follows:

# @macro dsl_method
# @method $1(${2--2})
# @return [${-1}] the return value of $0
create_method_with_args :foo, :a, :b, :c, String

生成： foo（a，b，c）和返回（String）create_method_with_args的返回值但我有兴趣像（$ {2--1}）这样的调用，每个都做| $ arg | ，并做文档说每个params with a single line of documentation。

generates: foo(a, b, c) and returns (String) the return value of create_method_with_args but I am interested in call something like (${2--1}).each do |$arg| and do documentation say each of the params with a single line of documentation.

推荐答案

不幸的是，重新简单的减少文档干燥的工具。由于安全性问题，我们选择不执行可执行宏（您可能不希望Ruby在您的评论中运行）。它们并不是一个一刀切的解决所有问题的解决方案，但它们在很简单的情况下工作得很好。插件仍然是更复杂的情况下推荐的方法。

Unfortunately macros are an extremely simplistic tool to reduce DRYness of docs. We opted out of implementing executable macros due to security concerns (you probably don't want Ruby running in your comments). They aren't really a one-size-fits-all solution to all problems, but they work well in the very simple cases. Plugins are still the recommended way to go for the more complicated cases.

表示，因为您仍然必须在某处指定实际参数文档 >，我没有看到一个插件怎么会简化你的任何事情。如果我是你，我只需将它定义为你已经拥有，并使用 @param 标签分别定义每个参数。例如（假设宏先前是在你的问题中附加的方式）：

That said, since you would still have to specify the actual parameter documentation somewhere, I don't see how even a plugin would simplify anything for you. If I were you, I would simply define it as you already have, and use @param tags to define each of the arguments separately. For example (let's assume the macro was previously "attached" the way you did in your question):

# @param [String] a documentation for a
# @param [Symbol] b documentation for b
# @param [Hash] c documentation for c
create_method_with_args :bar, :a, :b, :c, Fixnum

对我来说似乎很合理，因为在这些文档中没有什么可以干的。

That seems pretty reasonable to me, since there's not much else you can DRY up in those docs.

这篇关于迭代Yardoc“@宏”的寄存器的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！