Skip to content

This issue was moved to a discussion.

You can continue the conversation there. Go to discussion →

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
Skipants opened this issue Feb 15, 2023 · 3 comments
Closed

Comments

@Skipants
Copy link

Steps to reproduce

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

  1. Create a simple file standard_object.rb containing a class with a comment:
# hello world
class Base
end
  1. 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
Copy link
Author

Skipants commented Feb 15, 2023

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
Copy link
Owner

lsegal commented Apr 8, 2023

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
Copy link
Author

@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.

Repository owner locked and limited conversation to collaborators Aug 26, 2024
@lsegal lsegal converted this issue into discussion #1561 Aug 26, 2024

This issue was moved to a discussion.

You can continue the conversation there. Go to discussion →

Projects
None yet
Development

No branches or pull requests

2 participants