Missing @docstring in Resolver

Question

Missing @docstring in Resolver

stex opened this issue 7 years ago · 14 comments

With the current version, yard-junk fails for me with the following error:

NoMethodError: undefined method `object' for nil:NilClass
Did you mean?  object_id
/bundler/gems/yard-junk-868f67460bf5/lib/yard-junk/janitor/resolver.rb:75:in `object'

It looks like this was introduced with 1e9b8ca#diff-5c51ba5fedadbe17b766dec4de2d9b0c, removing the @docstring instance variable setting that Resolver#object still depends on.

Is this a bug or am I simply overlooking something?

Answer 1 · 2017-09-20T12:46:06.000Z

Ugh. Sorry, on it :(

Answer 2 · 2017-09-20T12:48:53.000Z

Funny. Could you please show the full backtrace?

Answer 3 · 2017-09-20T12:51:18.000Z

$ yard-junk
Running YardJunk janitor (version 0.0.6)...

/Users/stex/.rvm/gems/ruby-2.3.3@lopo/gems/yard-junk-0.0.6/lib/yard-junk/janitor/resolver.rb:75:in `object': undefined method `object' for nil:NilClass (NoMethodError)
Did you mean?  object_id
	from /Users/stex/.rvm/gems/ruby-2.3.3@lopo/gems/yard-0.9.9/lib/yard/templates/helpers/html_helper.rb:120:in `html_markup_rdoc'
	from /Users/stex/.rvm/gems/ruby-2.3.3@lopo/gems/yard-junk-0.0.6/lib/yard-junk/janitor/resolver.rb:34:in `resolve'
	from /Users/stex/.rvm/gems/ruby-2.3.3@lopo/gems/yard-junk-0.0.6/lib/yard-junk/janitor/resolver.rb:15:in `block in resolve_all'
	from /Users/stex/.rvm/gems/ruby-2.3.3@lopo/gems/yard-junk-0.0.6/lib/yard-junk/janitor/resolver.rb:15:in `each'
	from /Users/stex/.rvm/gems/ruby-2.3.3@lopo/gems/yard-junk-0.0.6/lib/yard-junk/janitor/resolver.rb:15:in `resolve_all'
	from /Users/stex/.rvm/gems/ruby-2.3.3@lopo/gems/yard-junk-0.0.6/lib/yard-junk/janitor.rb:22:in `block in run'
	from /Users/stex/.rvm/rubies/ruby-2.3.3/lib/ruby/2.3.0/benchmark.rb:308:in `realtime'
	from /Users/stex/.rvm/gems/ruby-2.3.3@lopo/gems/yard-junk-0.0.6/lib/yard-junk/janitor.rb:19:in `run'
	from /Users/stex/.rvm/gems/ruby-2.3.3@lopo/gems/yard-junk-0.0.6/exe/yard-junk:54:in `<top (required)>'
	from /Users/stex/.rvm/gems/ruby-2.3.3@lopo/bin/yard-junk:22:in `load'
	from /Users/stex/.rvm/gems/ruby-2.3.3@lopo/bin/yard-junk:22:in `<main>'
	from /Users/stex/.rvm/gems/ruby-2.3.3@lopo/bin/ruby_executable_hooks:15:in `eval'
	from /Users/stex/.rvm/gems/ruby-2.3.3@lopo/bin/ruby_executable_hooks:15:in `<main>'

Answer 4 · 2017-09-20T12:57:50.000Z

Ah, RDoc! Got it. Fixing.

Answer 5 · 2017-09-20T13:09:39.000Z

Could you please try current master?

Answer 6 · 2017-09-20T13:18:18.000Z

It doesn't raise an error any more, but is now showing warnings for our markdown README:

Running YardJunk janitor (version 0.0.6)...


Problems
--------
mistyped tags or other typos in documentation

doc/README.api.md:1: [InvalidLink] Cannot resolve link to </p> from text: {</p>
doc/README.api.md:1: [InvalidLink] Cannot resolve link to </p> from text: {</p>
doc/README.api.md:1: [InvalidLink] Cannot resolve link to base64_encoded_file from text: {{base64_encoded_file}
doc/README.api.md:1: [InvalidLink] Cannot resolve link to mime_type from text: {{mime_type}

This file is loaded using --readme in our .yardopts file and indeed contains lines like

"data:{{mime_type}};base64,{{base64_encoded_file}}"

However, I've never seen it being parsed as documentation.

Answer 7 · 2017-09-20T13:39:45.000Z

:philosoraptor: Can you please show your .yardopts, if any?

Answer 8 · 2017-09-20T13:41:56.000Z

# .yardopts
--plugin restful
--readme doc/README.api.md
lib/**/*.rb app/**/*.rb

yard-restful is used to generate our current API documentation (only files with @api_version are included in the output), but yard will traverse every file anyway.

Answer 9 · 2017-09-20T13:50:40.000Z

OK, I've got the problem. Now, it is funny. YARD does see README as documentation! If you insert {MyClassName} in README it would be auto-linked to MyClassName. But YARD doesn't complains if thing in {} does not exists (just fails to auto-link it, and fallbacks to plaintext), while yard-junk does complain (because if you'll write {My::Real::Class} there instead of {</p>}, you'd like to know if it is a typo).

So, the complains come in new version, because it have enchanced extra files (README and others) parsing and checking. ¯\_(ツ)_/¯

From all examples I can see, maybe it is reasonable to enclose things like "data:{{mime_type}};base64,{{base64_encoded_file}}" in backticks? This way everybody will be happy (I suppose it would be more readable too).

Answer 10 · 2017-09-20T13:53:50.000Z

This actually is already in backticks, I just didn't know how to escape them for Github:

I could switch to a different placeholder that doesn't use curly brackets, but shouldn't code examples be ignored anyway?

Answer 11 · 2017-09-20T13:54:47.000Z

Yep, they should! Checking it.

Answer 12 · 2017-09-20T14:28:14.000Z

Please, try current master. It should properly ignore code now.

Answer 13 · 2017-09-20T17:06:44.000Z

Works as expected now, thanks a lot for your help!

Answer 14 · 2017-09-21T02:47:09.000Z

Nice! It's 0.0.7 then.

Thanks for the help with debugging, and sorry for the quirks, we are kinda walking blind in the darkness here. Should create a huge test suite from existing OSS projects, probably.