11

I am writing documentation for my ruby gem using YARD. In my gem, I have some code which follows this common ruby pattern where a module is included in a class, and that module not only adds instance methods but it also adds class methods:

module Moo
  def self.included(klass)
    klass.extend ClassMethods
  end

  module ClassMethods
    def hello
      puts "hello"
    end
  end
end

class Foo
  include Moo
end

Foo.hello  # => class method runs, printing "hello"

By default, YARD will generate documentation for the Foo class that looks like this:

Inadequate documentation of the Foo class

I think this documentation is inadequate because it does not tell the user that the Foo.hello method is available. To learn about hello, the user has to click on Moo and then click on ClassMethods.

It would be great to have a list of all the class and instance methods of Foo on one page. How can I make that happen? Do I need to change the code, or is there a tag I can add to give YARD a hint about ClassMethods?

David Grayson
  • 84,103
  • 24
  • 152
  • 189
  • Did you try using [render](http://rubydoc.info/docs/yard/file/docs/GettingStarted.md#Rendering_Objects__render_____) on the embedded class? Don't know if it'd work like that or not. – Dave Newton Jan 15 '12 at 21:01
  • Thanks for the advice, but I tried and couldn't get it to render anything. Let me know if it works for you. – David Grayson Feb 23 '12 at 20:55

1 Answers1

8

Since v0.8.0 you can use the @!parse directive:

class Foo
  include Moo
  # @!parse extend Moo::ClassMethods
end
tmatilai
  • 4,071
  • 20
  • 24