Rdoc：如何记录委托？

Posted 2023-02-16

【中文标题】Rdoc：如何记录委托？

【英文标题】：Rdoc: How to document delegation?

【发布时间】：2021-01-04 15:58:01

【问题描述】：

我的类将一个方法委托给另一个对象（我将其称为辅助对象）。我想在委托类中包含该方法的文档，而不仅仅是委托类。程序员不应该使用辅助对象，只使用主对象，所以在辅助对象中记录不是很有用。

考虑这个例子。 Rdoc 输出有关 Node#initialize 和 Helper#hello 的文档。我想要关于Node#hello 的文档，就好像它只是另一种方法一样。有没有办法做到这一点？

require 'forwardable'

class Node
    extend Forwardable
    delegate %w(hello) => :@helper
    
    # Takes no params.
    def initialize
        @helper = Helper.new()
    end
end

class Helper
    
    # Outputs 'hello world'
    def hello
        puts 'hello world'
    end
end

-- 更新--

我试过院子。 yard 命令如下所示：

yardoc --no-private --protected app/**/*.rb -

我编辑了 ruby​​ 代码以尝试为 Node#hello 添加文档：

class Node
    extend Forwardable
    delegate %w(hello) => :@helper
    
    # Takes no params.
    def initialize
        @helper = Helper.new()
    end
    
    # @!method hello
    # Documentation for Node#hello
end

我运行yardoc的时候，好像说它处理了三个方法：

Files:           1
Modules:         0 (    0 undocumented)
Classes:         2 (    2 undocumented)
Constants:       0 (    0 undocumented)
Attributes:      0 (    0 undocumented)
Methods:         3 (    0 undocumented)
60.00% documented

如果我没有 # @!method 指令，那么它说它只处理两种方法：

Files:           1
Modules:         0 (    0 undocumented)
Classes:         2 (    2 undocumented)
Constants:       0 (    0 undocumented)
Attributes:      0 (    0 undocumented)
Methods:         2 (    0 undocumented)
50.00% documented

所以看起来Node#hello 的文档似乎是，但它并没有出现在实际文档中：

所以我不知道从那里去哪里。

【问题讨论】：

在 Yard 中，您使用 # @!method hello 重载和手动记录方法 - 据我所知，RDoc 没有等效的 directive。您可能想查看 rails guidelines 和示例源代码。

@max：请查看我对我的问题的更新。我尝试按照您建议的方式使用 yard，但似乎不太奏效。

嗯，用文档字符串作为detailed here 的更长格式是否有效？

啊哈！我想到了。 # @!method hello 标签必须在一行代码之上。独自坐着是行不通的。我将在我的答案中展示一个工作示例。谢谢！

【参考方案1】：

根据@max 的建议，我改用了 yard。使用 yard，我可以在没有任何实际方法的情况下创建方法文档：

# @!method hello()
# Outputs "hello world"
delegate %w(hello) => :@helper

请务必注意，文档必须高于实际代码。如果单独使用它是行不通的。