Every repository with this icon (
) is private.
Every repository with this icon (
) is public.
| Description: | YARD is a Ruby Documentation tool (Yay!) edit |
-
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,
TwPComments
-
0 votes
plugin loading raises exception when called from Rails
1 comment Created 3 days ago by lukemelia -
0 votes
String#underscore conflicts with ActiveSupport implementation
1 comment Created 3 days ago by lukemeliaFirst 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,
LukeComments
-
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.
Comments
Although not recommended, use @private and --no-private with yardoc or @api to declare your public/private api and --query to expose them. :nodoc: is generally a bad documentation habit, as that implies you are not documenting the specific method/module/class. This should ideally never be the case. Practically of course there are some cases where certain objects may be less important to your public API, but they should only be hidden in those contexts. :nodoc: fails to capture this semantic, where @private does. Also realize that hiding methods that are available to a programmer may make their lives more difficult and defeats the purpose of documentation. I won't claim to know your use case (there is a small handful of useful use cases for @private), but you should tread lightly if your habit is to :nodoc: every object you're personally uninterested in.
More here: http://yardoc.org/docs/yard/file:docs/WhatsNew.md
-
0 votes
[error]: NoMethodError: undefined method `meths' for #<yardoc constant ...
2 comments Created 10 days ago by boofHi, 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
Comments
-
0 votes
Param Named 'options' Fails to Render Correctly With @option Usage
3 comments Created 14 days ago by jherdmanSuppose 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 endWhen 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>Comments
A normal attribute looks like this:
<dt> <span class='type'>[<tt>Symbol</tt>]</span> <span class='name'>association_id</span> </dt> <dd> <span class='desc'><p> The name of this association </p></span></dd> -
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. :)
Comments
The parser does in fact document as much as it can. The errors listed in that referenced report do not stop it from generating HTML files; they're only notices that the parser failed at a certain point in the file. The parser continues to parse through the file.
Those specific errors are specific issues, though. The alias thing looks like a separate bug, but the class thing is expected output for such a problem. In that case it is properly explaining that the class cannot be documented any further.
-
Comments
-
Comments
jfirebaugh
Mon Aug 17 20:59:50 -0700 2009
| link
Yep, here's the reduction:
module Sequel module ADO module MSSQL module DatabaseMethods include Sequel::MSSQL::DatabaseMethods end end end end -
0 votes
formatting error with windows line endings and require
1 comment Created 3 months ago by jfirebaughSave the following with windows (CRLF) line endings:
require 'foo' # Test test # # Example: # example code def test endResulting 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.
Comments
-
# Test.test class Test def self.test end end # Shortcut for Test.test def Test Test.test endNeither 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"
Comments
Hi,
YARD does not autolink class names. Everything is plain English unless otherwised marked up. You should use the {OBJECT} syntax to link a class method as code. The reason it stops at Test. is because the summary reads until the end of the first sentence (ending with a period)-- because this is all plaintext, the first sentence ends at "Test."-- You'd want {Test.test} if you need the method to be linked.
jfirebaugh
Thu Aug 13 23:44:18 -0700 2009
| link
Thanks for the explanation.
This difference seems like it could be a barrier to adoption for projects considering switching from rdoc to yard, however. Is there a possibility for a switch to enable the rdoc cross-referencing behavior?
jfirebaugh
Thu Aug 13 23:59:17 -0700 2009
| link
Hmm, when I try your suggestion, the summary ends up reading "Shortcut for {Test." It is linked correctly in the details.
I don't think this would be a barrier to adoption. That would be like saying Textile's formatting could be a barrier to adoption to anyone using Markdown-- they're simply different markups. Frankly, I'd see the use of @param, @return and other tags a much bigger "barrier to entry" than having to add {} to the first instance of the class and method names in your docstrings.
That said, your report about {foo.bar} is right-- the
CodeObjects::Base#summarymethod needs to be beefed up to handle more complex sentence content.Another thing I should point out is if you're looking to document an inter-namespace "shortcut" (or any other reference), you should really consider using a @see tag:
# @see Test.test def Test; end
jfirebaugh
Fri Aug 14 08:33:42 -0700 2009
| link
Hi Loren,
Let me explain why I think it might be a barrier. I came across yard after browsing through rdoc-generated documentation for a lot of different projects and thinking "there must be something better." And yard looks great -- semantic markup, support for DSLs, extensible tags, and key for existing projects which are already invested in rdoc: compatible syntax. "By default, YARD is compatible with the same RDoc syntax most Ruby developers are already familiar with." This means that we can switch from rdoc to yard without immediately having to rewrite all the existing markup, and then incrementally begin using yardoc-specific tags to improve the existing documentation. In this scenario, each incompatibility with rdoc is a barrier to switching. If I have a lot of documentation which is (mostly) correctly cross-referenced by rdoc, and switching to yard would result in those cross-references disappearing until I go back and explicitly mark them all up, that becomes a reason for me not to switch. Not insurmountable by any means, but it will be the point at which someone considering yardoc is likely to go from thinking "yard looks great, and I think I'll be able to start using it in my projects without a lot of hassle" to "oh, it's going to take some work just to get back to the quality I had with rdoc." And that psychology will prevent people from switching, even if it turns out not to be that much work (for example, if it could largely be automated).
Thanks for the pointer too @see, I will check it out. And thanks for pushing the state of Ruby documentation tools forward.
John
-
0 votes
Use of method_missing in Registry chokes on #load override
1 comment Created 3 months ago by transI 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.
Comments
-
0 votes
Under Ruby 1.9.1, processing an RDoc formatted README fails
4 comments Created 3 months ago by francoisIf you clone git://github.com/francois/ad_gear_client.git and checkout 8073707, 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
Comments
Hi,
It's because the RDoc .document file in your project is specifying README.rdoc and LICENSE as Ruby files and YARD is trying to parse these.
I'm not positive if this how to specify .document files with RDoc, but as I understand it the file should specify what files RDoc should parse Ruby classes/methods out of.
RDoc will silently ignore these files but YARD is a bit more stingy when parsing invalid Ruby code so it will throw an error. I'll see what I can do about making YARD throw a warning, but you should probably remove those non-ruby file references from the .document file.
What do you mean? Which ".document"? There's no file by that name.
I see it in your ad_gear_client repo file listing in github, though gh won't let me click it because of the . prefix
.document about 4 hours ago Initial commit to ad_gear_client. [francois]When you do an ls -la you don't see that file in your local repo?
-
1 vote
Need to declare or load logger before overwriting formatter
2 comments Created 4 months ago by bbWith 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:19This can be easily solved by adding require 'logger' or an empty module in the core_ext/logger file.
Comments
I cannot reproduce this. core_ext/logger.rb was removed a few weeks back, so make sure you're trying on the latest master branch. If this still happens, reopen the ticket.
-
1 vote
requiring 'yard' breaks other rake tasks when using ActiveScaffold
5 comments Created 4 months ago by enricobI 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.
Comments
Cannot reproduce this with Rails 2.3.3. Perhaps this was either fixed in a YARD commit or in 2.3.3?
I've been using the yard gem. Is there a new version?
I'll try upgrading parts one at a time and see which update either fixes or changes the nature of the issue.
There is no new gem as of yet. I tried this with YARD 0.2.3.2 and it worked out with 2.3.3 under Ruby 1.8.6 and 1.9.1. You might want to also try with the code in github just to see if a recent change fixed it for 2.3.2 (since some loading stuff changed recently)
Just tried, but still getting the same error. I don't think that it's YARD and Rails alone. ActiveScaffold has something to do with this, too. >_<
I think I've just figured out what's causing the issue. Requiring 'yard' causes the following odd result while debugging ActiveScaffold's initialization:
>> ActiveScaffold::Helpers => Helpers
This causes confusion when ActiveScaffold tries to tell
ActionController::Baseto includeActiveScaffold::Helpers::ControllerHelpers.Is there something that yard's doing that could cause this?
-
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.
Comments
-
$ 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 binComments
GH's RubyGem build is badly designed. It doesn't like to rebuild gems if there is an existing gem in the index. I'd ask them to manually delete the gem but this is probably going to happen again if I ever pre-emptively update the .gemspec prior to a release.
I've disabled the GH gem index for yard. If you want the 0.2.3 release, you should use the rubyforge release. If you want to stay updated with the master branch git pull and
rake install -
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.
Comments
-
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.Comments
-
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:19Comments
Is the source for the project available to run tests on (if so, where)?
postmodern
Sun Jun 07 15:56:44 -0700 2009
| link
Hmm, it is working now. False alarm.
-
0 votes
Parameters header shows when there are parameters but no @param tags
1 comment Created 5 months ago by lsegal -
Is the answer to just make the methods private? Or is this something YARD can handle?
Example:
Comments
YARD has no short terms plan to support
:nodoc:out of the box. In 95% of the cases there is a better, documentable, solution to using that RDoc feature. The current position on:nodoc:is that it's prone to abuse and enables people to be lazy about their documentation habits. The goal of YARD is to improve not only the documentability of Ruby code, but the quality of documentation that comes out of Ruby projects. RDoc's:nodoc:feature has rarely ever been used to improve documentation quality and far more often been used detrimentally to ignore potentially important classes, modules or methods. The only real benefit is purely aesthetic (less classes in the class list in the generated documentation), but this can be dealt with in other ways.The short answer is probably not what you're looking to hear, but it's as follows: you should document your code. If you don't, people (especially in open source) should at least be aware of such an omission, and it should therefore should be apparent in your docs, not hidden from them. This allows your users (and potential contributors) to get on your case and get you to explain your code which in turn allows you to review some design decisions you made (why did I need to make this a private class again?). Even if the class is not "meant" for the outside world, it is definitely meant for someone. Someone in this case can range from the people maintaining the project all the way to people hacking with it some time in the future and needing to override some behaviour you've added in that class. The beauty of Ruby and other OOP languages is that when we design classes we design for code reuse. This is especially true with Ruby as overriding existing classes is often a reality (albeit, occasionally an ugly reality) of how things get done. When you omit documentation you stunt the reusability of the code because nobody knows about it. When I say documentation here, I don't necessarily mean explaining every line you write; often simply exposing the class name can be a huge help. That one class you made private and hid from documentation might be the one thing someone from another project would need to solve a similar problem.
The long answer is as follows: there are two potential ways to ignore a class from generated documentation. The first one, the
@apitag, is still under development and will be available in a later release. Users will be able to use this tag to expose certain classes, methods, modules to certain users by generating docs for a specific API (public, developer, etc.). The API name will be freeform and completely up to you to name. Feel free to help on implementing this feature! (#yard on freenode)The second solution involves a little hacking of YARD but still more or less supported (but not recommended for the reasons described above). In your Rakefile (use
-eto load an extra Ruby file if you're running from the command line) override the methodYARD::CLI::Yardoc#all_objectsto return the set of classes you want to generate documentation for. The default implementation returns all modules and classes, but you can replace it with, for example:class YARD::CLI::Yardoc def all_objects Registry.all(:module, :class).reject do |obj| %w( SomeMod::ClassToIgnore Class2 ... ).include?(obj.path) end end endHope this answers your question.
I completely agree with your goals. I'm looking forward to the @api tag.
Until it is actually supported, though, I can only point out the inconsistency of not supporting :nodoc: while supporting private. Since there is no way to have a private class in Ruby, there is no easy way to exclude a class or a constant from the doc although excluding a method is trivial. I feel it is inconsistent to condemn the existence of undocumented classes that the developper feels are part of the implementation and not part of the public API but condone undocumented methods made private for the exact same reason.
I think the goal of encouraging people to document and test the public API (and to write good code and release it as FOSS) should be ambitious enough; no need to put anyone in a situation where they will choose not to use your tool because it doesn't do what they want, and there is no easy way to do what they want. Note that the hack you are suggesting, which I find ugly and difficult to maintain, seems difficult if not impossible to use in some settings, like rdoc.info and docs.github.com
I would much appreciate support for :nodoc: or at least an alternative like @private until the @api tag is implemented.
-
Sometimes it makes more sense to document
&blockparameters as parameters, rather than as yields. However, the following:# @param block [#to_proc] Does stuff def foo(&block); enddoesn't display the block parameter.
Comments
-
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.
Comments
All tags can be attached to any code object (classs, module, method). In some cases they may seem non-sensical, the obvious examples being @param or @return for a class, however they are being recognized and stored. If a tag does not appear in documentation, this is not because the tag was ignored, instead it is most likely that there is no template to show the tag in documentation and a bug should be filed for that instead.
-
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 endComments
I think this is a fix:
` module YARD
module Generators::Helpersmodule HtmlHelper def tag_attrs(opts = {}) opts.map {|k,v| "#{k}=#{url.escape(v.to_s).inspect}" if v }.join(" ") end private # http://railsruby.blogspot.com/2006/07/url-escape-and-url-unescape.html def url_escape(string) string.gsub(/([^ a-zA-Z0-9_.-]+)/n) do '%' + $1.unpack('H2' * $1.size).join('%').upcase end.tr(' ', '+') end endend end
`I have yet to test this (I'm at school right now), but post back whether it works or not. I'll try this out myself when I get home.
This doesn't seem to work. Also,
HtmlHelperalready has aurlescapemethod. -
If I define a class as so:
class Foo attr_reader :stuff alias_method :my_stuff, :stuff endthe
my_stuffmethod isn't mentioned anywhere in the docs.Comments
-
An attribute created with
attr_readeris marked as RW when it is in fact read-only.Comments
YARD has the @overload tag to define method overloads in Ruby (see the list of tags in http://yard.soen.ca/getting_started#docing). There are no short-term plans to support RDoc's call-seq syntax in Ruby docs because the format is unable to properly associate docstrings and metadata with each method signature.