Question

如何为.each块中收集的定义编写文档？我的具体案例是Middleman，但我认为问题更为普遍，Google今天令人失望。

例如：

def manipulate_resource_list(resources)
    resources.each do |resource|
      # Provides a greeting
      # @return [string] Returns the greeting.
      def resource.hello_world
        'hello, world'
      end
    resources
end

我已经走到这一步了：

class ResourcesHandler < YARD::Handlers::Ruby::Base
  handles :def
  namespace_only

  def process
    if statement.method_name(true).to_sym == :manipulate_resource_list
      parse_block(statement.last.first.last.last, :owner => self.owner)
    end
  end
end

但这真的很糟糕，因为我必须实际记录这样的代码：

      # @!method hello_world
      # Provides a greeting
      # @return [string] Returns the greeting.
      { blank line 1 }
      { blank line 2 }
      def resource.hello_world
        'hello, world'
      end

...当YARD遇到YARD::Handlers::Ruby::MethodHandler: Undocumentable method defined on object instance时，我不得不担心def resource.hello_world。

注意：我想在声明附近的代码中记录，而不是文件的某些远程部分。

知道如何改进我的YARD资源处理程序以使其更自然吗？

Answer 1

好吧，我最终使用了这个：

class ResourcesHandler < YARD::Handlers::Ruby::Base
  handles :def
  namespace_only

  def process
    if statement.method_name(true).to_sym == :manipulate_resource_list

      # Block consists of everything in the actual `do` block
      block = statement.last.first.last.last
      block.each do | node |
        if node.type == :defs
          def_docstring = node.docstring
          def_name = node[2][0]
          object = YARD::CodeObjects::MethodObject.new(namespace, "resource.#{def_name}")
          register(object)
          object.dynamic = true
          object[:docstring] = def_docstring
          object[:group] = 'Resource Extensions'
          puts node.type
        end
      end
    end
  end
end

YARD - 资源处理程序 - 记录.each块中声明的defs

1 个答案: