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

Nested constants don't seem to be handled properly #1505

Closed
findhumane opened this issue Aug 29, 2023 · 2 comments
Closed

Nested constants don't seem to be handled properly #1505

findhumane opened this issue Aug 29, 2023 · 2 comments

Comments

@findhumane
Copy link

One common technique to define enumerations in Ruby that I like does not seem to be handled by YARD properly.

Steps to reproduce

This is the minimal reproduction for the issue. I've done my best to remove
all extraneous code and unique environment state on my machine before providing
these steps:

  1. Create yard_nested_constants.rb:
    class YardNestedConstants
      # Attributes for products
      PRODUCT_ATTRIBUTES = [
    
        # The name of the product.
        PRODUCT_NAME = :product_name,
    
        # The name of the producer.
        PRODUCER = :producer,
      ]
    end
  2. Run the following command:
    yard doc
    
  3. Open browser to doc/YardNestedConstants.html

Actual Output

Screenshot_20230828_225721

Expected Output

Documentation of PRODUCT_NAME and PRODUCER should be processed.

Environment details:

  • OS: Fedora Linux 37
  • Ruby version (ruby -v): ruby 3.1.4p223 (2023-03-30 revision 957bb7cb81) [x86_64-linux]
  • YARD version (yard -v): yard 0.9.34

I have read the Contributing Guide.

@lsegal
Copy link
Owner

lsegal commented Sep 17, 2023

By default YARD only processes top-level statements for performance as well as correctness reasons. As a workaround, it wouldn't be too difficult to write a plugin to automatically handle this case:

# place in a file like `.yard/ext/array_constant_handler.rb`
class ArrayConstantHandler < YARD::Handlers::Ruby::Base
  handles :assign
  namespace_only

  process do
    arr = statement[1]
    arr.children.each {|c| parse_block(c) } if arr.type == :array
  end
end

Place -e .yard/ext/array_constant_handler.rb in your .yardopts or pass that arg to yard doc on the command line.

You can package that up in a gem that has the yard-YOURNAME prefix and can then use --plugin YOURNAME instead of the -e argument (assuming the gem is installed).

You could also build this out as a Directive to be a bit more surgical about when this logic gets invoked. It would be similarly simple.

It's currently unclear to me if this is something that is widely needed in YARD core; this is the first time it's popped up as a feature request. Experimenting with a plugin could identify how commonly used the idiom is in the wild, and if it is, it could be merged in.

@findhumane
Copy link
Author

That worked, thanks!

Repository owner locked and limited conversation to collaborators Aug 26, 2024
@lsegal lsegal converted this issue into discussion #1558 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