lsegal / yard Goto Github PK
View Code? Open in Web Editor NEWYARD is a Ruby Documentation tool. The Y stands for "Yay!"
Home Page: http://yardoc.org
License: MIT License
YARD is a Ruby Documentation tool. The Y stands for "Yay!"
Home Page: http://yardoc.org
License: MIT License
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.
$ 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
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. :)
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.
An attribute created with attr_reader
is marked as RW when it is in fact read-only.
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.
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.
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.
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.
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.
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
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.
Header should not be displayed
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
Try running yardoc
on this:
# @private
class Foo; end
Foo
is in no way ignored.
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.
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.
Although no error is given if a class has a @see
tag, this tag doesn't show up in the generated documentation.
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
The return type for any initialize method should automatically default to the enclosing class type.
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");
}
}
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.
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.
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.
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'
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
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
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
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.
class Foo
def foo=(a); end
end
The output of this only has a "foo" instance method.
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 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
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
I occasionally have code that deals with fixed-width arrays such as zip
ped 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
Is the answer to just make the methods private? Or is this something YARD can handle?
Example:
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.
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.
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.
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.
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.
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
The listing of methods included from a module includes private methods of that module.
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>
# 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"
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
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:in
require'
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:in
gem_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:in
load'
from /usr/bin/yardoc:19
This can be easily solved by adding require 'logger' or an empty module in the core_ext/logger file.
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 ...
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.
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 in
overriding_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: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'
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.