search

lsegal / yard

YARD is a Ruby Documentation tool. The Y stands for "Yay!"
http://yardoc.org
MIT License
1.95k stars 398 forks source link

Can't generate stdlib docs for Ruby 1.9.3 #491

Closed SFEley closed 12 years ago

SFEley commented 12 years ago

So I'm trying to create my own YARD documentation for the Ruby 1.9.3 p125, using this blog post from lsegal as a guide. Creating the core documentation from *.c (the first step) worked fine, but trying to generate the standard library documentation fails. After a number of other warnings, I get the exception below:

[warn]: in YARD::Handlers::Ruby::MethodHandler: Undocumentable method defined on object instance
[warn]:     in file 'lib/singleton.rb':137:

    137: def klass.instance # :nodoc:

[warn]: Load Order / Name Resolution Problem on SyntaxError:
[warn]: -
[warn]: Something is trying to call to_sym on object SyntaxError before it has been recognized.
[warn]: This error usually means that you need to modify the order in which you parse files
[warn]: so that SyntaxError is parsed before methods or other objects attempt to access it.
[warn]: -
[warn]: YARD will recover from this error and continue to parse but you *may* have problems
[warn]: with your generated documentation. You should probably fix this.
[warn]: -
/Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/code_objects/proxy.rb:218:in `rescue in method_missing': Proxy cannot call method #to_sym on object 'SyntaxError' (YARD::CodeObjects::ProxyMethodError)
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/code_objects/proxy.rb:215:in `method_missing'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/code_objects/proxy.rb:45:in `initialize'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/code_objects/class_object.rb:133:in `new'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/code_objects/class_object.rb:133:in `superclass='
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/parser/c_parser.rb:83:in `handle_class'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/parser/c_parser.rb:65:in `handle_namespace'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/parser/c_parser.rb:367:in `block in parse_namespaces'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/parser/c_parser.rb:361:in `scan'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/parser/c_parser.rb:361:in `parse_namespaces'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/parser/c_parser.rb:15:in `parse'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/parser/source_parser.rb:438:in `parse'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/parser/source_parser.rb:361:in `parse_in_order'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/parser/source_parser.rb:89:in `block in parse'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/logging.rb:66:in `enter_level'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/parser/source_parser.rb:88:in `parse'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard.rb:18:in `parse'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/cli/yardoc.rb:215:in `run'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/lib/yard/cli/command.rb:13:in `run'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/gems/yard-0.7.5/bin/yardoc:4:in `<top (required)>'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/bin/yardoc:19:in `load'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/bin/yardoc:19:in `<main>'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/bin/ruby_bundler_wrapper:23:in `eval'
    from /Users/Steve/.rvm/gems/ruby-1.9.3-p125@global/bin/ruby_bundler_wrapper:23:in `<main>'

The warning text says that "YARD will recover from this error and continue to parse" but it doesn't. The command halts after the backtrace. I noticed that SyntaxError was defined in errors.c so I tried to run it again with all of the *.c files first, and it got past that error, but then hit a similar one on method ASN1ObjectId#child. At that point I decided I didn't want to try to try any harder to resolve a chain of load order problems, and logged this issue instead.

Is there anything that can be done? It'd be really great to access core and stdlib documentation via yri. Thanks.

lsegal commented 12 years ago

This is fixed in master (0.8 is due out next month). A workaround would be to add errors.c to the glob, ie.: yardoc errors.c lib