Running `yard docs --tag owner` fails to generate on classes with comments

Skipants commented 1 year ago

Steps to reproduce

POC can also be found at: https://github.com/Skipants/yard-poc/tree/master/error-converting-class-to-string

Create a simple file standard_object.rb containing a class with a comment:
```
# hello world
class Base
end
```
Run yard doc --tag owner standard_object.rb

Actual Output

This errors with [error]: Exception occurred while generating 'Base.html'

Full debug:

➜ error-converting-class-to-string (master) ✗ yard doc --tag owner --debug standard_object.rb
[debug]: Parsing ["standard_object.rb"] with `ruby` parser
[debug]: Parsing standard_object.rb
[debug]: Serializing to .yardoc/objects/root.dat
[debug]: Re-generating object ...
[debug]: Re-generating object Base...
[debug]: Generating asset js/jquery.js
[debug]: Serializing to doc/js/jquery.js
[debug]: Generating asset js/app.js
[debug]: Serializing to doc/js/app.js
[debug]: Generating asset js/full_list.js
[debug]: Serializing to doc/js/full_list.js
[debug]: Generating asset css/style.css
[debug]: Serializing to doc/css/style.css
[debug]: Generating asset css/common.css
[debug]: Serializing to doc/css/common.css
[debug]: Generating asset css/full_list.css
[debug]: Serializing to doc/css/full_list.css
[debug]: Generating asset class_list.html
[debug]: Serializing to doc/class_list.html
[debug]: Generating asset method_list.html
[debug]: Serializing to doc/method_list.html
[debug]: Generating asset file_list.html
[debug]: Serializing to doc/file_list.html
[debug]: Generating asset frames.html
[debug]: Serializing to doc/frames.html
[debug]: Serializing to doc/index.html
[debug]: Serializing to doc/_index.html
[debug]: Serializing to doc/top-level-namespace.html
[error]: Exception occurred while generating 'Base.html'
[error]: TypeError: no implicit conversion of YARD::CodeObjects::RootObject into String
[error]: Stack trace:
    /Users/andrewszczepanski/.rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/yard-0.9.28/lib/yard/templates/template.rb:268:in `block (2 levels) in run'
    /Users/andrewszczepanski/.rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/yard-0.9.28/lib/yard/templates/template.rb:258:in `each'
    /Users/andrewszczepanski/.rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/yard-0.9.28/lib/yard/templates/template.rb:258:in `block in run'
    /Users/andrewszczepanski/.rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/yard-0.9.28/lib/yard/templates/template.rb:400:in `add_options'
    /Users/andrewszczepanski/.rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/yard-0.9.28/lib/yard/templates/template.rb:257:in `run'
    /Users/andrewszczepanski/.rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/yard-0.9.28/lib/yard/templates/template.rb:279:in `block in yieldall'

Files:           1
Modules:         0 (    0 undocumented)
Classes:         1 (    0 undocumented)
Constants:       0 (    0 undocumented)
Attributes:      0 (    0 undocumented)
Methods:         0 (    0 undocumented)
 100.00% documented

Expected Output

Expecting regular output as if run without a custom tag:

➜ error-converting-class-to-string (master) ✗ yard doc standard_object.rb
Files:           1
Modules:         0 (    0 undocumented)
Classes:         1 (    0 undocumented)
Constants:       0 (    0 undocumented)
Attributes:      0 (    0 undocumented)
Methods:         0 (    0 undocumented)
 100.00% documented

Environment details:

OS: [Mac OS / Ventura 13.2]
Ruby version (ruby -v): ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [arm64-darwin21]
YARD version (yard -v): yard 0.9.28

I have read the Contributing Guide. ✅

Skipants commented 1 year ago

The obvious problem here is a collision between the tag name and some internals of YARD.

One way that seems obvious to fix it is to just .to_s the class name that it tires to convert. That happens at:

lib/yard/templates/template.rb#268

I have that fix on my fork right now, but I am a little worried that there's still going to be some weirdness with that and I'm looking into it. I am also trying to ensure that the HTML output is as expected.

lsegal commented 1 year ago

Sorry for the late reply:

Can you explain a bit about the use case for --tag owner? I assume this is a custom tag you've used in certain places? If so, then yes, it seems like you might have hit on a reserved name. The best fix here would be to namespace your custom tags.

I think there is a fix that can be applied here (and the reason for the "will accept PR" tag on this issue), but the fix would probably not be what you're looking for: a warning when passing --tag owner for a reserved name, along with the ignoring of this tag.

Skipants commented 1 year ago

@lsegal No worries at all! I appreciate all you do!

Yes, the owner tag is a custom one we are using ourselves.

I have found that this commit fixes it but I'm not exactly sure why. I just tackled the symptom without fully understanding the problem. We've been generating docs and serving them on a yard server for at least a month now without issue, though.

I can put up a PR for that and if any issues come up we can go from there.

lsegal / yard