Using a single @overload tag to override the description of the method signature is resulting in duplicate method descriptions and duplicate "Returns:" blocks. The duplicate "Returns:" are explained by the un-overloaded return description and the overloaded return description. The duplicate descriptions are baffling.

If the user supplies an @overload as the first line, then the standard yardoc description and returns should not be generated.

Blessings,
TwP

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.

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

similar to documenting ruby classes which overload java classes, see #23, overloading modules doesn't work. Instead of warning, it throws an exception:

    29:  module org::example::SomeInterface
    30:  end

It would be really great if this worked as the project I'm trying to migrate to YARD throws thousands of lines of error code at the moment.

The error message for reference:
Unhandled exception in YARD::Handlers::Ruby::Legacy::ModuleHandler:
NoMethodError: undefined method to_sym' for nil:NilClass<br/> inoverriding_java.rb`:29:

    /Library/Ruby/Gems/1.8/gems/yard-0.2.3.2/bin/../lib/yard/code_objects/base.rb:95:in `initialize'
    /Library/Ruby/Gems/1.8/gems/yard-0.2.3.2/bin/../lib/yard/code_objects/namespace_object.rb:12:in `initialize'
    /Library/Ruby/Gems/1.8/gems/yard-0.2.3.2/bin/../lib/yard/code_objects/base.rb:78:in `new'
    /Library/Ruby/Gems/1.8/gems/yard-0.2.3.2/bin/../lib/yard/code_objects/base.rb:78:in `new'
    /Library/Ruby/Gems/1.8/gems/yard-0.2.3.2/bin/../lib/yard/handlers/ruby/legacy/module_handler.rb:6:in `process'
    /Library/Ruby/Gems/1.8/gems/yard-0.2.3.2/bin/../lib/yard/handlers/processor.rb:23:in `process'

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");
    }
}