lsegal / yard
- Source
- Commits
- Network (21)
- Issues (6)
- Downloads (14)
- Wiki (8)
- Graphs
-
Branch:
master
Pledgie Donations
Once activated, we'll place the following badge in your repository's detail box:
YARD is a Ruby Documentation tool (Yay!)
YARD is a documentation generation tool for the Ruby programming language. It enables the user to generate consistent, usable documentation that can be exported to a number of formats very easily, and also supports extending for custom Ruby constructs such as custom class level definitions.
— Read more
-
when including Yard(0.5.2) I ran into the issue where it would overwrite the functionality of the class method [] on Hash. See this gist: http://gist.github.com/265483
Comments
-
0 votes
When an additional template directory is added for code generation, the setup.rb file is not processed unless the format output directory is present (e.g. 'html', 'text' etc.) Code example:
app/controllers/profiles_controller.rb
class ProfilesController < ApplicationController
... # @drop profile # @return a template def show@profile = @brand.profiles.find(params[:id]) ...end
yard/drop_plugin.rb
require 'pathname'
template_dir = Pathname.new(File.dirname(FILE) + '/templates').realpath.to_s
puts template_dir
YARD::Templates::Engine.register_template_path(template_dir)
puts YARD::Templates::Engine.template_paths.inspectYARD::Tags::Library.define_tag("Drop Variable", :drop)
yard/templates/default/tags/setup.rb
puts "self:#{self.inspect}"
def init
super sections.last.place(:drop).before(:return) puts 'Tags override read' enddef drop
tag :drop endconsole output for yardoc -e yard/drop_plugin.rb -p yard/templates/ app/controllers/profiles_controller.rb --debug
pcp071939pcs:profile-full-svn delwateo$ yardoc -e yard/drop_plugin.rb -p yard/templates/ app/controllers/profiles_controller.rb --debug
/Users/delwateo/code/profile-full-svn/yard/templates ["/Users/delwateo/.gem/ruby/1.8/gems/yard-0.5.2/bin/../lib/../templates", "/Users/delwateo/code/profile-full-svn/yard/templates"] [debug]: Parsing app/controllers/profiles_controller.rb withruby18parser [debug]: Processing app/controllers/profiles_controller.rb... [debug]: Serializing to .yardoc/objects/ProfilesController/load_profile_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/show_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController.dat [debug]: Serializing to .yardoc/objects/ProfilesController/rsa_section_vars_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/public_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/reset_password_i.dat [debug]: Serializing to .yardoc/objects/root.dat [debug]: Serializing to .yardoc/objects/ProfilesController/blocking_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/render_private_view_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/force_public_profile_3F_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/index_order_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/following_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/complete_password_reset_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/render_public_view_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/index_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/render_brand_section_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/new_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/following_profile_3F_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/activate_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/comments_pagination_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/followers_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/create_i.dat [debug]: Serializing to .yardoc/objects/ProfilesController/render_owners_view_i.dat [debug]: Serializing to doc/js/jquery.js [debug]: Serializing to doc/js/app.js [debug]: Serializing to doc/js/full_list.js [debug]: Serializing to doc/css/style.css [debug]: Serializing to doc/css/full_list.css [debug]: Serializing to doc/css/common.css [debug]: Serializing to doc/method_list.html [debug]: Serializing to doc/class_list.html [debug]: Serializing to doc/file_list.html [debug]: Serializing to doc/_index.html [debug]: Serializing to doc/index.html [debug]: Serializing to doc/file.README.html [debug]: Serializing to doc/ProfilesController.html [debug]: Serializing to doc/top-level-namespace.htmldoc/ProfilesController.html
- (Object) show
A template
Returns:
- a template
Comments
-
Hi,
Any chance you could clean up these warnings?
/usr/local/lib/ruby/gems/1.8/gems/yard-0.4.0/lib/rubygems_plugin.rb:17: warning: method redefined; discarding old has_rdoc? /usr/local/lib/ruby/gems/1.8/gems/yard-0.4.0/lib/rubygems_plugin.rb:55: warning: method redefined; discarding old setup_rdoc
Regards,
Dan
Comments
-
I still can't build the gem documentation, so I installed the yard-doc-core-1.8.7 to try yri.
After installing, this happens:
[02:15 PM] root@fizz :: ~ # yri Array /usr/lib/ruby/gems/1.8/gems/yard-0.5.1/bin/../lib/yard/cli/yri.rb:45:in `initialize': No such file or directory - /root/.yard/yri_cache (Errno::ENOENT)If I make that directory, it works fine -- I can see the Array documentation.
Comments
-
yardoc's gem documentation isn't working for me -- it quits almost immediately and silently.
[03:07 AM] root@fizz :: ~ # yardoc --re-build-gems --debug --verbose [03:07 AM] root@fizz :: ~ # wha? wha?: command not found [03:08 AM] root@fizz :: ~ # yri YARD No documentation for `YARD' [03:08 AM] root@fizz :: ~ # yri Array No documentation for `Array' [03:08 AM] root@fizz :: ~ # yri Gem No documentation for `Gem'Comments
-
Ruby 1.8.7
Rubygems 1.3.5
OS XThis shows up with warnings on. Can you clean this up please?
/usr/local/lib/ruby/gems/1.8/gems/yard-0.4.0/lib/rubygems_plugin.rb:17: warning: method redefined; discarding old has_rdoc?
Comments
-
0 votes
Methods ending in question mark ? cannot be found
2 comments Created 19 days ago by steveykenIn YARD, search for "matches_dynamic_method?"
A result for ActionMailer::Base is returned, click the link to "matches_dynamic_method?" and the result is "We could not find any information about ActionMailer::Base.matches_dynamic_method. Are you sure it exists in the project rails?"
Notice that its looking for "ActionMailer::Base.matches_dynamic_method" not "ActionMailer::Base.matches_dynamic_method?" i.e. the ? is missing most likely because its being interpreted as the query string part of the URL.
Comments
-
I'm getting the error 'wrong argument type Symbol (expected Proc)' when running yardoc on my code. You can reproduce it like this:
git clone git://github.com/wedesoft/multiarray.git cd multiarray git branch yardoc-test v0.2.1 git checkout yardoc-test yardocI used Ruby-1.8.6 and yardoc-0.4.0.
Comments
Ok. I was using the latest Gem from http://gemcutter.org/gems/yard . I retrieved the current version from the Github repository and it works. Thanks.
-
In a global overview doc file (using Markdown), I am mixing code sample with more generic data I would like to be rendred in
<pre>tags. When using the 4 spaces indent, the code and data are both syntax highlighted as Ruby code. How to selectively disable highlighting for some blocks ? (I don't want to use the global --no-highlight flag).Thanks.
Comments
YARD doesn't help much with markup. The 1.9 parser will avoid highlighting if the code is not valid Ruby, so using Ruby1.9 is your best bet here. If that's not an option, you'll have to opt out of YARD's highlighting with
--no-highlightand use another markup processor that does its own syntax highlighting. Maruku is a good choice for that.A syntax like:
!!!plaintext unhighlighted textMight be added sometime in the future, unless you want to take a stab at a patch.
-
Links in the instance attribute summary don't point at the Instance Attribute Details but at some not existing file.
This, however, only seems to haven when @overload'ing the attr_accessor. Example code can be found at https://gist.github.com/f722fddc375e5e77574f
Comments
-
1 vote
Information about undefined return value is placed wrong for instance attributes
1 comment Created 25 days ago by dominikhWhile 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.Comments
-
1 vote
Method signatures only show the first defined return type
1 comment Created 25 days ago by dominikhwhen having a documentation string like
# @return [String, Integer] def foo # ... endThe method signature only shows String
- (String) fooI 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.
Comments
Show multiple types in signature return types and add heuristics for nullable/splat returns
Summary of the new heuristics are as follows:
Single return type: (Type) Two return types: (TypeA, TypeB) More than two: (TypeA, ...) @return [Type, nil]: (Type?) [? is superscripted] @return [Type, Array]: (Type+) [+ is superscripted] @return [void]: no return type shownClosed by 497696a
-
It looks like one is not able to document one's own setter methods.
attr_reader :foo # some description def foo=(val) # ... endThe setter won't be added to the docs at all.
# some description attr_reader :foo # another description attr_setter :foo def foo=(val) # ... endwill only list the setter in the docs, not the getter.
Comments
-
0 votes
2 comments Created about 1 month ago by postmodernInvalid byte sequences in templates.0.4.1xI 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'Comments
-
0 votes
Default description for attributes, .new, etc. is RDoc-specific
1 comment Created about 1 month ago by nex3The 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.
Comments
-
0 votes
1 comment Created about 1 month ago by nex3The "methods included from" list in a class includes private methods0.4.1x -
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
Comments
This error occurs only when [ require 'yard' ] is present in the Rakefile. Replacing this with [ require 'yard/rake/yardoc_task' ] fixes the issue.
TwP
You have to [ require 'yard' ] in order for the YardocTask to run properly. Therefore the collision with the namespace method definition is unavoidable.You should only be using require 'yard', which automatically loads the rake task when needed.
However I don't see why this is an issue, Module is a subclass of Object and rake tasks run within Object context, so the Module#namespace method should be unreachable from a rake task. More poignantly, I can't reproduce an issue in either 1.8.7 or 1.9:
require 'yard' p self.class namespace "foo" do desc "FOO!" task "bar" do puts "hi" end end YARD::Rake::YardocTask.newrake -Tgives:Object rake foo:bar # FOO rake yard # Generate YARD DocumentationAnd both
rake foo:barandrake yardseem to both be callable and work just fine.Do you have a specific Rakefile that fails?
I'm sharing rake tasks by putting them into a module and then loading the module into a Rakefile. Hence, my module is calling the namespace method defined in the yard core_ext folder.
-
The return type for any initialize method should automatically default to the enclosing class type.
Comments
This is already done AFAIK, is there a place where it does not?
It is done if you have not specified a @return tag. However, if you put in something like ...
@return self
It shows the return type as Object instead of the class. Don't know if this is user error or intended behavior.
There's currently no special handling for names in return types, it's simply a bunch of words that are linked (if they can be), for now. In the future, when there's a standardized format, there may be some better shortcuts. Until then this is the expected behaviour.
-
1 vote
1 comment Created about 1 month ago by TwP0.4.1xDefault return type for query? methodsstylex -
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,
TwPComments
-
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
Comments
When you say class overview, what are you referring to? http://yardoc.org/docs/TwP-servolux looks right to me
The Servolux::Daemon class has a lengthy explanation of how to use the class just above the class declaration. RDoc will capture this class comment and put it at the top of the file. Yard used to do this (version 2.3.5.1) but the latest release no longer pulls in this data for this particular gem.
http://github.com/TwP/servolux/blob/master/lib/servolux/daemon.rb
All the leading commentary is not showing up in yardoc output.
TwP
If you would like a more real-time conversation, IM me at tim(dot)pease(at)gmail(dot)com using your favorite jabber IM client.
Okay, I confirmed this bug in with the legacy parser and in 1.8. Should be fixed soon.
Note that you have a "# class Servolux::Daemon" following the end of your class definition. If you remove that, the prepended comments should show up- YARD is just getting confused because it accepts both prepended comments and comments appended to the end of the line. I will make it so that the legacy parser takes the prepended comments at a higher precedence.
Legacy parser should prioritize prepended comments over appended ones.
Closed by e545ba0
I'm still getting this error. I pulled down the change you made, installed the gem and run it against my project. The odd thing is that it caught and parsed the text for one class, but no others.
http://github.com/sprsquish/blather/tree/better-docs
the "better-docs" branch of Blather
It looks correct to me: http://yardoc.org/docs/sprsquish-blather/Blather/Client
Anything wrong on any of the pages? I'm seeing everything you would expect.
hm.. that all looks right. what options did you pass in?
I'm building my docs with the rake task. And I don't get the search box in the upper left
The search box is a customization for the live docs at yardoc.org. I tested this locally, though, and I get the same results. I simply used
yardocin the base directory, which is what the Rake task does by default as well. Verify that you've properly updated yard (yardoc -v), and make sure to delete 0.2.3.5 if you still have it, the rubygems plugin is known to interfere.I tested this in 1.8 as well. Same result:
Generated on Tue Nov 17 02:15:51 2009 by yard 0.4.0 (ruby-1.8.7).Perhaps your gem install in 1.8 is not using the stable branch and doesn't have the recent changes?
I updated both from the cloned repo.
The other odd thing is that the Index isn't in alphabetical order on 1.8.7.
-
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
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.
-
0 votes
plugin loading raises exception when called from Rails
1 comment Created about 1 month ago by lukemelia -
0 votes
String#underscore conflicts with ActiveSupport implementation
1 comment Created about 1 month 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
Thanks for pointing out @private. I agree with your position, but there is one situation that can arise in OO languages where something like :nodoc: is appropriate: internal protocols. Sometimes, two objects within a module need to cooperate in some special way, e.g. in FFI bindings some object implements #to_ptr to return its underlying FFI::Pointer representation, but the implementer wishes to hide the bindings' FFI underpinnings completely.
In a language like Haskell, this problem doesn't exist because it's possible to pick and choose which methods a module should export, regardless of what types they operate on, and Haskell documentation tools only cover exported functions. Some OO languages support friend types, allowing related data types to share private methods. In a simpler type system like Ruby's, :nodoc: (and @private) is the best we can do.
Best,
Jeremy
I certainly understand the internal protocol use case. That's pretty much why @private exists, to try and make Ruby's visibilities more granular than they are. :nodoc: is a little different though, because even internal protocols should have some form of documentation (ideally)-- using :nodoc: implies no documentation, which can occasionally be extremely unhelpful, even for methods that are not part of a "public" API. Many Ruby projects have poor documentation because they abuse that functionality; YARD's trying to change that behaviour.
But yea, if your use case is the internal protocol deal then @private is exactly what you should use.
Regards,
Loren
-
0 votes
[error]: NoMethodError: undefined method `meths' for #<yardoc constant ...
2 comments Created about 1 month 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 about 1 month 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 4 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 4 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 4 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 5 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 6 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 7 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. -
One idiom I use kind of a lot is something like the following:
class Foo Bar = Struct.new(:field1, :field2, :field3) endYARD has no way of documenting the fields, or indeed the struct itself, since docstrings on constants aren't displayed.
Comments
-
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
looks like this only affects 1.8.6 as well: http://github.com/lsegal/yard/blob/master/lib/yard/core_ext/hash.rb
Fix improper Hash.[] implementation
Closed by f45f05d