It's currently not possible to generate docs for ruby methods which overload Java classes.

It would be great if YARD would just accept classes defined in JRuby style. Recreating the package structure as modules would be a plus!

Here's some reference:

A warning and the source is shown:

# overriding a java class
class org::example::Test # this is line 16
  # a new method for Test
  def i_am_new
    puts "i am new"
  end

  # @overload test() from java
  def self.test
    puts "test in ruby"
  end
end

The Java code (which would be documented via javadoc, no worries here):

package org.example;
class Test {
    public static void test() {
        System.out.println("test in java");
    }
}

In the following code, the references to #bar in the text and using @see both resolve (properly) to Foo#bar. However, the RefTag doesn't.

class Foo
  # @param a [String]
  def bar(a)
  end

  # {#bar}
  # @param (see #bar)
  # @see #bar
  def baz(a)
  end
end

class Foo
  # @option options :foo [String] It's foo!
  # @option options :bar [String] It's bar!
  def bar(options)
  end

  # @param options (see Foo#bar)
  def baz(options)
  end
end

I would expect the documentation for #baz to make some mention of Foo#bar, whether it be by copying over the entire options documentation or just linking to it and providing a canned description.

One idiom I use kind of a lot is something like the following:

class Foo
  Bar = Struct.new(:field1, :field2, :field3)
end

YARD has no way of documenting the fields, or indeed the struct itself, since docstrings on constants aren't displayed.

I occasionally have code that deals with fixed-width arrays such as zipped arrays and so forth. There's no good way to document this with YARD. I'd suggest something like the following:

# @param items [Array<(Fixnum, String)>]
def multiply_each(items)
  items.map {|times, item| item * times}
end

Consider the following README.rdoc:

Hi! Here's a link: http://www.github.com I like fruits[http://www.apple.com].

With rdoc, two links will be generated, one entitled "www.github.com", the other one entitled "fruits". yard doesn't generate either.

Suppose you have a class like this:

class Foo
  # @param [Hash] options foo bar baz
  # @option options [Boolean] :awesome set to true for awesome
  def bar(options={})
  end
end

When using YARD version 0.2.3.5, the 'options' parameter will not have its HTML correctly rendered. The following is the rendered HTML:

<dl>
      <dt>Options Hash <tt>options</tt></dt>
<dd>
  <div class="option">
    <table>
      <tr>
        <th class="name">Key Name</th>
        <th class="default">Default Value</th>
        <th class="type">Accepted Types</th>
        <th class="desc">Description</th>
      </tr>

        <tr>
          <td class="name">:awesome</td>
          <td class="default">

              <span class="na">N/A</span>

          </td>
          <td class="type">[<tt>Boolean</tt>]</td>
          <td class="desc"><p>
set to true for awesome
</p>
</td>
        </tr>
    </table>

Hi, I have built a lib called V. This lib creates it's own classes and modules during runtime. But when I try to yard it, it breaks and I get this:

[error]: NoMethodError: undefined method `meths' for #<yardoc constant V::Adapters::Git::Operations>
[error]: in generator YARD::Generators::ClassGenerator: /Users/florian/.rvm/gems/ruby-enterprise/1.8.6/gems/yard-0.2.3.5/lib/../templates/default/class/html/header.erb
[error]: /Users/florian/.rvm/gems/ruby-enterprise/1.8.6/gems/yard-0.2.3.5/lib/yard/code_objects/base.rb:167:in `method_missing'
/Users/florian/.rvm/gems/ruby-enterprise/1.8.6/gems/yard-0.2.3.5/lib/yard/code_objects/proxy.rb:142:in `__send__'
/Users/florian/.rvm/gems/ruby-enterprise/1.8.6/gems/yard-0.2.3.5/lib/yard/code_objects/proxy.rb:142:in `method_missing'
/Users/florian/.rvm/gems/ruby-enterprise/1.8.6/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:60:in `included_meths'
/Users/florian/.rvm/gems/ruby-enterprise/1.8.6/gems/yard-0.2.3.5/lib/yard/generators/base.rb:285:in `inject'
/Users/florian/.rvm/gems/ruby-enterprise/1.8.6/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:58:in `each'
/Users/florian/.rvm/gems/ruby-enterprise/1.8.6/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:58:in `inject'
/Users/florian/.rvm/gems/ruby-enterprise/1.8.6/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:58:in `included_meths'
/Users/florian/.rvm/gems/ruby-enterprise/1.8.6/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:57:in `map'
/Users/florian/.rvm/gems/ruby-enterprise/1.8.6/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:57:in `included_meths'
/Users/florian/.rvm/gems/ruby-enterprise/1.8.6/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:52:in `meths'

source: github.com/boof/v

There seems to be no easy way to suppress Ruby certain code objects from appearing in generated docs. If it's easier to support this using a tag such as `@nodoc', that would be a fine solution.