Doesn't seem to work #4

alexgb opened this Issue Mar 2, 2011 · 21 comments

This looks really helpful, but doesn't seem to work with current versions, 1.1.3 or 1.1.2, of Sinatra. I'm not getting the routes documented from yardoc and I get an empty array from YARD::Sinatra.routes


Hm. Me too...


Same here. I also noticed a warning "Error loading plugin 'yard-sinatra'", so I did:

[sloveless@sloveless-mbp:turducken]$ yardoc --plugin sinatra --verbose --debug app/controllers/test_results.rb 
[warn]: Error loading plugin 'yard-sinatra'
[warn]: Error loading plugin 'yard-sinatra'
[debug]: Parsing ["app/controllers/test_results.rb"] with `ruby` parser
[debug]: Processing app/controllers/test_results.rb...
[debug]: Serializing to .yardoc/objects/root.dat
[info]: Re-generating object ...
[debug]: Serializing to doc/js/jquery.js
[debug]: Serializing to doc/js/app.js
[debug]: Serializing to doc/js/cucumber.js
[debug]: Serializing to doc/js/full_list.js
[debug]: Serializing to doc/css/style.css
[debug]: Serializing to doc/css/common.css
[debug]: Serializing to doc/css/cucumber.css
[debug]: Serializing to doc/css/full_list.css
[debug]: Serializing to doc/feature_list.html
[debug]: Serializing to doc/tag_list.html
[debug]: Serializing to doc/class_list.html
[debug]: Serializing to doc/method_list.html
[debug]: Serializing to doc/file_list.html
[debug]: Serializing to doc/frames.html
[debug]: Serializing to doc/_index.html
[debug]: Serializing to doc/index.html
[debug]: Serializing to doc/file.README.html
[debug]: Serializing to doc/top-level-namespace.html
[debug]: Serializing to doc/js/cucumber.js
[debug]: Serializing to doc/requirements.html
[debug]: Serializing to doc/requirements/step_transformers.html
[debug]: Serializing to doc/requirements/tags.html
Files:           1
Modules:         0 (    0 undocumented)
Classes:         0 (    0 undocumented)
Constants:       0 (    0 undocumented)
Methods:         0 (    0 undocumented)
NaN% documented

Not sure other info I can get than my env info:

[sloveless@sloveless-mbp:turducken]$ gem env
RubyGems Environment:
  - RUBY VERSION: 1.9.2 (2011-07-09 patchlevel 290) [x86_64-darwin11.1.0]
  - INSTALLATION DIRECTORY: /Users/sloveless/.rvm/gems/ruby-1.9.2-p290
  - RUBY EXECUTABLE: /Users/sloveless/.rvm/rubies/ruby-1.9.2-p290/bin/ruby
  - EXECUTABLE DIRECTORY: /Users/sloveless/.rvm/gems/ruby-1.9.2-p290/bin
    - ruby
    - x86_64-darwin-11
     - /Users/sloveless/.rvm/gems/ruby-1.9.2-p290
     - /Users/sloveless/.rvm/gems/ruby-1.9.2-p290@global
     - :update_sources => true
     - :verbose => true
     - :benchmark => false
     - :backtrace => false
     - :bulk_threshold => 1000
     - :sources => [""]

Using yard 0.7.2 and yard-sinatra 1.0.0.


yard 0.7.3 and yard-sinatra 1.0.0 also fails.

tried with the debug and verbose output in the previous comment. There were no load errors or other indications of problems, it just doesnt appear to do anything.


Sorry, github tells me, for some reason that "Notifications for new comments on this Issue are off.", so I didn't get email notifications about this. I won't have time to investigate until next week or so. It is definitely not related the the Sinatra version. It's probably some changes in Yard...


Not working for me either:

Using sinatra (1.3.1)
Using yard (0.7.3)
Using yard-sinatra (1.0.0)

Looks like a really useful tool however!


With yard 0.7.4 I don't get an error but these warnings instead:

/Users/tomdz/.rvm/gems/ruby-1.8.7-p352/gems/yard-0.7.4/lib/yard.rb:2: warning: already initialized constant VERSION
/Users/tomdz/.rvm/gems/ruby-1.8.7-p352/gems/yard-0.7.4/lib/yard.rb:5: warning: already initialized constant ROOT
/Users/tomdz/.rvm/gems/ruby-1.8.7-p352/gems/yard-0.7.4/lib/yard.rb:8: warning: already initialized constant TEMPLATE_ROOT
/Users/tomdz/.rvm/gems/ruby-1.8.7-p352/gems/yard-0.7.4/lib/yard.rb:11: warning: already initialized constant CONFIG_DIR
/Users/tomdz/.rvm/gems/ruby-1.8.7-p352/gems/yard-0.7.4/lib/yard.rb:33: warning: already initialized constant RUBY19
/Users/tomdz/.rvm/gems/ruby-1.8.7-p352/gems/yard-0.7.4/lib/yard.rb:33: warning: already initialized constant RUBY18
/Users/tomdz/.rvm/gems/ruby-1.8.7-p352/gems/yard-0.7.4/lib/yard.rb:39: warning: already initialized constant CONTINUATIONS_SUPPORTED

and the routes seem to get documented as if they are normal methods.


Confirmed working with yard 0.7.4 (Well, working in the sense that the stuff is documented. I get the same warnings as tomdz)

[EDIT] Starts messing up and duplicating methods if you add tags


I summon thee, @lsegal!

ql commented Jan 19, 2012

I have same duplication problem too. Here is example:


Ah, this is interesting. The duplication comes from the fact that YARD now auto-detects DSL syntax and generates a method (via macros) if there is a docstring attached to them in the "explicit form", or if there are tags attached to the docstring. The "explicit form" is when you have a '##' on the first line of the comment, in the form:

# This is an explicit docstring
get '/foo' ...

In this case, both YARD and yard-sinatra are each creating separate methods. One solution is to not use the '##' explicit form, but if you have @tags this can't be dealt with as easily. There are two things that might need to change here:

First, perhaps YARD should not detect DSL methods that are not valid method names. statement like get '/foo' should probably not be detected as defining a method /foo. I've opened lsegal/yard#464 to track and fix this.

However, this would not solve scenarios like: get 'foo'. yard-sinatra could do a few things to solve this. Firstly, yard-sinatra could define its behaviour as a set of macros instead of handlers-- this would make YARD use the attached macros rather than a macro and handler separately.

I should point out that you can bascially get the behaviour of this plugin using the macros feature. The gist that @ql pasted can be rewritten as:

# The API
class Api
  # @macro [attach] sinatra.get
  #   @method $1
  #   @overload GET '$1'
  # Says hello
  get '/hello' do
    body "hello"

  # The bar method
  get '/bar' do
    body "bar"

The above works with just yard (no plugins).

The only problem with this code is that users have to define the macros manually (you can see this done in the first get call. So, a yard-sinatra plugin still does have a reason to exist, namely, to define these macros so that users don't have to.


For reference, yard-sinatra could define macros programmatically using:

include YARD::Parser
include YARD::CodeObjects

SourceParser.before_parse_list do |files, globals|
  globals.__attached_macros ||= {}

  ['get', 'post', 'put'].each do |name|
    doc = "@method $1\n@overload #{name.upcase} '$1'"
    macro = MacroObject.create("sinatra.#{name}", doc, P("Object.#{name}"))
    (globals.__attached_macros[name] ||= []) << macro

And handlers would not be needed.


This makes sense. Thanks a ton, I'll look into this as soon as I have time.

@tjeden tjeden was assigned Jan 20, 2012
@tjeden tjeden closed this Jan 27, 2012
@tjeden tjeden reopened this Jan 27, 2012

I just tried the suggestion made by @lsegal while using yard 0.7.5, but it doesn't work there because of the change introduced by lsegal/yard#464. Namely, the DSL methods are not being processed because the URL paths don't look like valid method names. Instead, yard prints warnings for those methods and leaves them unprocessed:

[warn]: in YARD::Handlers::Ruby::MacroHandler: Undocumentable method, missing name
[warn]:     in file 'my/sinatra_app.rb':123:

    123: get "/do/something" do

The macro works fine as suggested for yard 0.7.4. Is there any chance that this plugin can fix this for vesion 0.7.5 by somehow overriding the method name handling? Is there some other way to work around this issue?


@javanthropus, just add ## to the first line of your docstring to force YARD to recognize it, or provide a @method tag (or @overload) to specify the method name manually. That should work in 0.7.5.


@lsegal, I tried adding ## as you suggested both as the first line of the docstring alone as well as the first line with content following it on the line, but that didn't change the behavior. Adding @method works but only after removing the macro I defined. Of course, the point of the macro was to avoid manually duplicating the sinatra route I'm trying to document within the documentation itself.

Am I just doing something wrong?


@javanthropus you shouldn't need to remove the macro, you can use both the @macro and @method, but you have to remove the @method $1 definition from the macro itself. This won't work, because $1 in this case is not a valid method name. YARD needs a proper Ruby method name to be able to register that object as one, and there's no way for it to guess what the method would be in those cases, so you need to specify the name manually (like @method _get_hello). Ideally the plugin would generate the proper method name for you, but it would need updating for this.


Thanks for your help, @lsegal. After trying a few more things, I came to the same conclusion as you regarding my present options. I figured the plugin would need to contribute something here that the macro alone couldn't handle anymore.


Doesn't work in yard 0.8.1


Any ideas on how either the macro approach or the yard-sinatra plugin could work for extensions, so that is DSL routes and settings defined as a class-scope function and called in self.registered(app) ?


Would overwriting the DSLHandlerMethods be of any use? Sure doesn't show any errors while doc creation. 573a173210

@rkh rkh referenced this issue Jul 17, 2012

Handle PATCH method. #8


On a related news: It seems to work on the first parse and if you force a reparse.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment