Try running yardoc on this:

# @private
class Foo; end

Foo is in no way ignored.

class Foo
  def foo=(a); end
end

The output of this only has a "foo" instance method.

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 inoverriding_java.rb`:29:

[error]: Stack trace:
/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:ininitialize'
/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:innew'
/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:inprocess'

The @yield in the following code is ignored:

class Foo
  # @yield Stuff and who-knows-what
  def bar
  end
end

Without this, there's no way to document a method that yields without any parameters.

While the notice "This method returns an undefined value." usually stands on its own line for methods, it is displayed inline for instance attributes
It is shown as:
This method returns an undefined value. Sets the content of the input line.
While it should be shown as:
This method returns an undefined value.
Sets the content of the input line.

An attribute created with attr_reader is marked as RW when it is in fact read-only.

If you clone git://github.com/francois/ad_gear_client.git and checkout 8073707aafb8b2f4eff634d31848111162d5b2bf, you'll get this:

$ ruby19 ruby --version
ruby 1.9.1p0 (2009-01-30 revision 21907) [i386-darwin9.6.0]

$ ruby19 rake doc --trace
(in /Users/francois/Projects/ad_gear_client)
** Invoke doc (first_time)
** Invoke doc:clean (first_time)
** Execute doc:clean
rm -rf doc
** Execute doc
rake aborted!
syntax error in `README.rdoc`:(1,1): syntax error, unexpected '='
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/parser/ruby/ruby_parser.rb:280:in `on_parse_error'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/parser/ruby/ruby_parser.rb:25:in `parse'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/parser/ruby/ruby_parser.rb:25:in `parse'
/opt/ruby19/lib/ruby/1.9.1/ripper/core.rb:18:in `parse'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/parser/source_parser.rb:129:in `parse_statements'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/parser/source_parser.rb:84:in `parse'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/parser/source_parser.rb:49:in `parse_in_order'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/parser/source_parser.rb:23:in `block in parse'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/logging.rb:22:in `enter_level'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/parser/source_parser.rb:22:in `parse'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard.rb:6:in `parse'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/registry.rb:38:in `load'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/registry.rb:17:in `method_missing'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/cli/yardoc.rb:35:in `run'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/cli/yardoc.rb:12:in `run'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/yard-0.2.3.3/lib/yard/rake/yardoc_task.rb:29:in `block in define'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:617:in `call'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:617:in `block in execute'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:612:in `each'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:612:in `execute'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:578:in `block in invoke_with_call_chain'
/opt/ruby19/lib/ruby/1.9.1/monitor.rb:190:in `mon_synchronize'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:571:in `invoke_with_call_chain'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:564:in `invoke'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:2027:in `invoke_task'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:2005:in `block (2 levels) in top_level'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:2005:in `each'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:2005:in `block in top_level'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:2044:in `standard_exception_handling'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:1999:in `top_level'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:1977:in `block in run'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:2044:in `standard_exception_handling'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/lib/rake.rb:1974:in `run'
/opt/ruby19/lib/ruby/gems/1.9.1/gems/rake-0.8.4/bin/rake:31:in `'
/opt/ruby19/bin/rake:19:in `load'
/opt/ruby19/bin/rake:19:in `'

The tree is http://github.com/francois/ad_gear_client/tree/8073707aafb8b2f4eff634d31848111162d5b2bf

I have a Rails 2.3.2 application with ActiveScaffold and I am trying to define a rake task for generating YARD documentation.

The rake task itself works, but if I then try to use another rake task (for example rake spec), it fails with the following error message:

uninitialized constant Helpers::ControllerHelpers
/Library/Ruby/Gems/1.8/gems/activesupport-2.3.2/lib/active_support/dependencies.rb:440:in `load_missing_constant'
/Library/Ruby/Gems/1.8/gems/activesupport-2.3.2/lib/active_support/dependencies.rb:80:in `const_missing'
/Users/enrico/Projects/csic/wit/trunk/vendor/plugins/active_scaffold/environment.rb:8
/Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in `gem_original_require'
/Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in `require'
/Library/Ruby/Gems/1.8/gems/activesupport-2.3.2/lib/active_support/dependencies.rb:156:in `require'
/Library/Ruby/Gems/1.8/gems/activesupport-2.3.2/lib/active_support/dependencies.rb:521:in `new_constants_in'
/Library/Ruby/Gems/1.8/gems/activesupport-2.3.2/lib/active_support/dependencies.rb:156:in `require'
/Users/enrico/Projects/csic/wit/trunk/vendor/plugins/active_scaffold/init.rb:8:in `evaluate_init_rb'
/Library/Ruby/Gems/1.8/gems/rails-2.3.2/lib/rails/plugin.rb:146:in `evaluate_init_rb'
/Library/Ruby/Gems/1.8/gems/activesupport-2.3.2/lib/active_support/core_ext/kernel/reporting.rb:11:in `silence_warnings'
/Library/Ruby/Gems/1.8/gems/rails-2.3.2/lib/rails/plugin.rb:142:in `evaluate_init_rb'
/Library/Ruby/Gems/1.8/gems/rails-2.3.2/lib/rails/plugin.rb:48:in `load'
/Library/Ruby/Gems/1.8/gems/rails-2.3.2/lib/rails/plugin/loader.rb:38:in `load_plugins'
/Library/Ruby/Gems/1.8/gems/rails-2.3.2/lib/rails/plugin/loader.rb:37:in `each'
/Library/Ruby/Gems/1.8/gems/rails-2.3.2/lib/rails/plugin/loader.rb:37:in `load_plugins'
/Library/Ruby/Gems/1.8/gems/rails-2.3.2/lib/initializer.rb:348:in `load_plugins'
/Library/Ruby/Gems/1.8/gems/rails-2.3.2/lib/initializer.rb:163:in `process'
/Library/Ruby/Gems/1.8/gems/rails-2.3.2/lib/initializer.rb:113:in `send'
/Library/Ruby/Gems/1.8/gems/rails-2.3.2/lib/initializer.rb:113:in `run'
/Users/enrico/Projects/csic/wit/trunk/config/environment.rb:9
/Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in `gem_original_require'
/Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in `require'
/Library/Ruby/Gems/1.8/gems/activesupport-2.3.2/lib/active_support/dependencies.rb:156:in `require'
/Library/Ruby/Gems/1.8/gems/activesupport-2.3.2/lib/active_support/dependencies.rb:521:in `new_constants_in'
/Library/Ruby/Gems/1.8/gems/activesupport-2.3.2/lib/active_support/dependencies.rb:156:in `require'
/Library/Ruby/Gems/1.8/gems/rails-2.3.2/lib/tasks/misc.rake:4
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:636:in `call'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:636:in `execute'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:631:in `each'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:631:in `execute'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:597:in `invoke_with_call_chain'
/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/monitor.rb:242:in `synchronize'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:590:in `invoke_with_call_chain'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:607:in `invoke_prerequisites'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:604:in `each'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:604:in `invoke_prerequisites'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:596:in `invoke_with_call_chain'
/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/monitor.rb:242:in `synchronize'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:590:in `invoke_with_call_chain'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:607:in `invoke_prerequisites'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:604:in `each'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:604:in `invoke_prerequisites'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:596:in `invoke_with_call_chain'
/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/monitor.rb:242:in `synchronize'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:590:in `invoke_with_call_chain'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:607:in `invoke_prerequisites'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:604:in `each'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:604:in `invoke_prerequisites'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:596:in `invoke_with_call_chain'
/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/monitor.rb:242:in `synchronize'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:590:in `invoke_with_call_chain'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:583:in `invoke'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:2051:in `invoke_task'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:2029:in `top_level'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:2029:in `each'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:2029:in `top_level'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:2068:in `standard_exception_handling'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:2023:in `top_level'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:2001:in `run'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:2068:in `standard_exception_handling'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/lib/rake.rb:1998:in `run'
/Library/Ruby/Gems/1.8/gems/rake-0.8.7/bin/rake:31
/usr/bin/rake:19:in `load'
/usr/bin/rake:19

I know that ActiveScaffold defines a constant called ActiveScaffold::Helpers::ControllerHelpers, so it seems as though YARD is interfering with ActiveScaffold's initialization.

I'm not sure whose bug this is, so I have also sent a identical bug report to ActiveScaffold.

Although no error is given if a class has a @see tag, this tag doesn't show up in the generated documentation.

Attempting to generate yardoc for http://github.com/jeremyevans/sequel/tree/master:

rake aborted!
stack level too deep
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/core_ext/symbol_hash.rb:22:in `block in update'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/core_ext/symbol_hash.rb:22:in `each'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/core_ext/symbol_hash.rb:22:in `update'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/core_ext/symbol_hash.rb:24:in `merge'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:60:in `block (2 levels) in included_meths'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:58:in `each'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:58:in `inject'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:58:in `block in included_meths'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:57:in `map'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:57:in `included_meths'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:52:in `meths'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/proxy.rb:142:in `method_missing'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:60:in `block (2 levels) in included_meths'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:58:in `each'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:58:in `inject'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:58:in `block in included_meths'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:57:in `map'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:57:in `included_meths'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/namespace_object.rb:52:in `meths'
/opt/local/lib/ruby1.9/gems/1.9.1/gems/yard-0.2.3.5/lib/yard/code_objects/proxy.rb:142:in `method_missing'
[...]

Let me know if there's something I can do to find a reduction. I'm not sure where to begin looking.

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>

The default description for a read-only attribute is "Returns the value of attribute +name+." Note the +es. These aren't rendered as <code> by markdown, and so end up looking very incongruous.

I suggest storing defaults like this as raw HTML that never gets touched by the specific markup processor.

# Test.test
class Test
  def self.test
  end
end

# Shortcut for Test.test
def Test
  Test.test
end

Neither instance of Test.test is linked in the output. Rdoc does so.

In addition, the summary for #Test reads "Shortcut for Test." rather than "Shortcut for Test.test"

class Foo
  def bar; end
  alias_method :bar2, :bar
end

The Foo#bar2 method doesn't have a permalink. As a consequence, {Foo#bar2} creates a broken link.

Sometimes it makes more sense to document &block parameters as parameters, rather than as yields. However, the following:

# @param block [#to_proc] Does stuff
def foo(&block); end

doesn't display the block parameter.

With the current head, I get the following error when running plain yardoc:

$ yardoc
/Library/Ruby/Gems/1.8/gems/yard-0.2.3.2/bin/../lib/yard/core_ext/logger.rb:2: uninitialized constant Logger (NameError)
from /Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in gem_original_require' from /Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:inrequire'
from /Library/Ruby/Gems/1.8/gems/yard-0.2.3.2/bin/../lib/yard.rb:15
from /Library/Ruby/Gems/1.8/gems/yard-0.2.3.2/bin/../lib/yard.rb:14:in each' from /Library/Ruby/Gems/1.8/gems/yard-0.2.3.2/bin/../lib/yard.rb:14 from /Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:ingem_original_require'
from /Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in require' from /Library/Ruby/Gems/1.8/gems/yard-0.2.3.2/bin/yardoc:2 from /usr/bin/yardoc:19:inload'
from /usr/bin/yardoc:19

This can be easily solved by adding require 'logger' or an empty module in the core_ext/logger file.

The return type for any initialize method should automatically default to the enclosing class type.

The listing of methods included from a module includes private methods of that module.

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

A method name containing punctuation won't have the question mark escaped in the link to the method, making those links invalid.

For example:

class Foo
  def <<; end
  def foo?; end
end

I've tried to use several tags (such as @see) in places where they aren't supported, and this just silently fails. It would be great if it raised a warning like other unrecognized tags.

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.

rdoc.info has been experiencing some problems generating documentation for code that has certain edge-cases. Here's a few examples: http://github.com/zapnap/rdocinfo/issues/#issue/22/comment/53150

Some parsing errors, some metaprogramming ambiguity... but the real problem is that when YARD hits a problem like that, it totally gives up and doesn't document that file.

Handling every possible edge-case is hard, but perhaps the parser could handle errors more gracefully -- documenting as much of the class as it can and skipping the part with errors. Right now, it throws the entire class away. :)

rdoc has the "call-seq" flag that allows you to change how the a method signature is displayed. It would be wonderful if yardoc could support this flag as well.

Blessings,
TwP

It looks like one is not able to document one's own setter methods.

attr_reader :foo

# some description
def foo=(val)
  # ...
end

The setter won't be added to the docs at all.

# some description
attr_reader :foo

# another description
attr_setter :foo

def foo=(val)
  # ...
end

will only list the setter in the docs, not the getter.

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

Empty "Todo Item:" header pops up all the time when @todo tag is not used.

Simplest example:
# @param arg this is arg
def meth(arg)
end

...yardoc will insert "Todo item:" even in this case.

when having a documentation string like

# @return [String, Integer]
def foo
  # ...
end

The method signature only shows String
- (String) foo

I don't know if this is a design rational (because multiple return values could become too messy), but I consider it rather confusing, especially if it is equally likely that the first or the second return type gets returned.

class Foo
  private
  def foo; end
end

Although Foo#foo doesn't show up on the page for the Foo class, it does show up in the Method List frame.

Rake defines a namespace method on Object. It is used to declare rake namespaces for tasks. Yard also declares a namespace method on Module which it uses when generating documentation. However, when you require 'yard/rake/yardoc_task' the original rake namespace method is overwritten. The yard rake task is unusable for this reason.

TwP

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.

First off, thanks for YARD. It's pretty sweet.

We're using YARD to dynamically generate some API documentation in our Rails app. Putting aside the question of how advisable that may or may not be, doing a require 'yard' causes problems with subsequent class loading in Rails. Here's a demonstration of the issue:

>> "ActiveRecord::Errors".underscore
=> "active_record/errors"
>> require 'yard'
=> ["RUBY19", "RUBY18", "YARD"]
>> "ActiveRecord::Errors".underscore
=> "active_record::errors"

Cheers,
Luke

I use Roll, a library manager, during development. It overrides Kernel#load to do it's thing. B/c you use #method_missing in Registry, my #load method is being picked up rather than yours. Quick fix is to add the #load method explicitly:

  module YARD
    class Registry
      DEFAULT_YARDOC_FILE = ".yardoc"

      include Singleton

      @objects = {}

      class << self
        attr_reader :objects

        # MY FIX
        def load(files, reload=false)
          instance.load(files, reload)
        end

        def method_missing(meth, *args, &block)
          if instance.respond_to? meth
            instance.send(meth, *args, &block)
          else
            super
          end
        end

        def clear
          instance.clear
          objects.clear
        end
      end

      attr_accessor :yardoc_file
      attr_reader :proxy_types

      ...

method_missing can be fragile. It would be best to ditch it and define the methods explicitly or use delegate.rb.

Also, Singleton is generally considered unnecessary in Ruby. You could probably just use:

module Registry
extend self
...

Though I haven't looked at the code close enough to know for sure.

HTH.

Save the following with windows (CRLF) line endings:

require 'foo'

# Test test
#
# Example:
#  example code
def test
end

Resulting output: the summary for #test contains the example code, rather than "Test test." It works as expected if saved with Unix line endings, or without the require.

Header should not be displayed

Is the answer to just make the methods private? Or is this something YARD can handle?

Example:

http://rdoc.info/rdoc/thoughtbot/shoulda/blob/7d6aa5b6ecceef0bef3399bc328275a3700e06ac/Shoulda/ActiveRecord/Matchers/AllowMassAssignmentOfMatcher.html#protected_attributes-instance_method

While testing out yard-graph on an existing RDoced project, I noticed it crashed while generating UML graphs.

$ yard-graph --full
/usr/lib/ruby/gems/1.8/gems/yard-0.2.3/bin/../lib/yard/generators/uml_generator.rb:64:in `process_objects': undefined method `each' for false:FalseClass (NoMethodError)
from /usr/lib/ruby/gems/1.8/gems/yard-0.2.3/bin/../lib/yard/generators/uml_generator.rb:41:in `init'
from /usr/lib/ruby/gems/1.8/gems/yard-0.2.3/bin/../lib/yard/generators/base.rb:171:in `call'
from /usr/lib/ruby/gems/1.8/gems/yard-0.2.3/bin/../lib/yard/generators/base.rb:171:in `run_before_generate'
from /usr/lib/ruby/gems/1.8/gems/yard-0.2.3/bin/../lib/yard/generators/base.rb:169:in `each'
from /usr/lib/ruby/gems/1.8/gems/yard-0.2.3/bin/../lib/yard/generators/base.rb:169:in `run_before_generate'
from /usr/lib/ruby/gems/1.8/gems/yard-0.2.3/bin/../lib/yard/generators/base.rb:134:in `generate'
from /usr/lib/ruby/gems/1.8/gems/yard-0.2.3/bin/../lib/yard/generators/base.rb:127:in `each'
from /usr/lib/ruby/gems/1.8/gems/yard-0.2.3/bin/../lib/yard/generators/base.rb:127:in `generate'
from /usr/lib/ruby/gems/1.8/gems/yard-0.2.3/bin/../lib/yard/cli/yard_graph.rb:22:in `run'
from /usr/lib/ruby/gems/1.8/gems/yard-0.2.3/bin/../lib/yard/cli/yard_graph.rb:8:in `run'
from /usr/lib/ruby/gems/1.8/gems/yard-0.2.3/bin/yard-graph:4
from /usr/bin/yard-graph:19:in `load'
from /usr/bin/yard-graph:19

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

When running YARD inside a Rails process, Gem.source_index returns a rails object which doesn't respond to :all_gems so load_plugins blows up.

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

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:

[warn]: in YARD::Handlers::Ruby::Legacy::ClassHandler: Undocumentable class: class org::example::Test
[warn]: in file 'overriding_java.rb':16:

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

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.

$ sudo gem install lsegal-yard
Successfully installed lsegal-yard-0.2.3
1 gem installed

$ yardoc --help
/Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in `gem_original_require': no such file to load -- /Library/Ruby/Gems/1.8/gems/lsegal-yard-0.2.3/bin/../lib/yard (LoadError)
        from /Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in `require'
        from /Library/Ruby/Gems/1.8/gems/lsegal-yard-0.2.3/bin/yardoc:2
        from /usr/bin/yardoc:19:in `load'
        from /usr/bin/yardoc:19

$ ls -l /Library/Ruby/Gems/1.8/gems/lsegal-yard-0.2.3/
total 48
-rw-r--r--  1 root  admin   1792 17 jui 00:03 FAQ.markdown
-rw-r--r--  1 root  admin   1059 17 jui 00:03 LICENSE
-rw-r--r--  1 root  admin  10508 17 jui 00:03 README.markdown
-rw-r--r--  1 root  admin    879 17 jui 00:03 Rakefile
drwxr-xr-x  5 root  admin    170 17 jui 00:03 bin

http://github.com/TwP/servolux

Trying to use yardoc to generate documentation. No failures, but there is no class overview being generated using yard v0.4.0 (the whole nine). Most likely a failure on the part of the user, but darned if I know where the problem lies :-/

TwP

If I define a class as so:

class Foo
  attr_reader :stuff
  alias_method :my_stuff, :stuff
end

the my_stuff method isn't mentioned anywhere in the docs.

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 noticed that under Ruby 1.9.1, there are "invalid byte sequences" in the built in YARD templates.

** Invoke docs (first_time)
** Invoke yard (first_time)
** Execute yard
rake aborted!
invalid byte sequence in US-ASCII
/usr/lib/ruby19/gems/1.9.1/gems/yard-0.4.0/lib/yard/templates/template.rb:255:in `gsub!'
/usr/lib/ruby19/gems/1.9.1/gems/yard-0.4.0/lib/yard/templates/template.rb:255:in `file'
/usr/lib/ruby19/gems/1.9.1/gems/yard-0.4.0/templates/default/fulldoc/html/setup.rb:59:in `block in generate_assets'
/usr/lib/ruby19/gems/1.9.1/gems/yard-0.4.0/templates/default/fulldoc/html/setup.rb:57:in `each'
/usr/lib/ruby19/gems/1.9.1/gems/yard-0.4.0/templates/default/fulldoc/html/setup.rb:57:in `generate_assets'
/usr/lib/ruby19/gems/1.9.1/gems/yard-0.4.0/templates/default/fulldoc/html/setup.rb:9:in `init'
/usr/lib/ruby19/gems/1.9.1/gems/yard-0.4.0/lib/yard/templates/template.rb:130:in `initialize'
/usr/lib/ruby19/gems/1.9.1/gems/yard-0.4.0/lib/yard/templates/template.rb:84:in `new'
/usr/lib/ruby19/gems/1.9.1/gems/yard-0.4.0/lib/yard/templates/template.rb:89:in `run'
/usr/lib/ruby19/gems/1.9.1/gems/yard-0.4.0/lib/yard/templates/engine.rb:93:in `generate'
/usr/lib/ruby19/gems/1.9.1/gems/yard-0.4.0/lib/yard/cli/yardoc.rb:60:in `run'
/usr/lib/ruby19/gems/1.9.1/gems/yard-0.4.0/lib/yard/rake/yardoc_task.rb:64:in `block in define'

Any method that ends in a question mark should have a default return type of Boolean instead of Object. A method such as empty? or closed? should default to Boolean.

Blessings,
TwP

Hi, I'm trying to document my plugin code (http://github.com/be9/acl9) and stuck with the @overload stuff not showing the @param's.

I've simplified it down to this: http://gist.github.com/128641
Overloads themselves are shown in the generated docs, whereas parameters are not.