CODEWITHSUNDEEP
rubyrdoc
tscheingeld
tscheingeld

Reputation: 849

Rdoc: How to document delegation?

My class delegates a method to another object (which I'll call the helper object). I want to include documentation of that method in the delegating class, not just the delegated class. The programmer should not use the helper object, only the main object, so documenting in the helper object isn't very useful.

Consider this example. Rdoc outputs documentation about Node#initialize and Helper#hello. I want to have documentation about Node#hello as if it were just another method. Is there a way to do that?

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

-- update --

I tried yard. The yard command looks like this:

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

I edited the ruby code to try to add documentation for 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

When I run yardoc, it seems to say that it processes three methods:

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

If I don't have the # @!method directive then it says it only processes two methods:

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

So it seems like it seems that documentation for Node#hello, but it doesn't appear in the actual documentation:

enter image description here

So I'm not sure where to go from there.

Upvotes: 1

Views: 354

Answers (1)

tscheingeld
tscheingeld

Reputation: 849

On advice from @max, I switched to yard. Using yard, I can create method documentation without any actual method like this:

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

It's important to note that the documentation has to be above actual code. It won't work if it's by itself.

Upvotes: 1

Related Questions