include inside class << self

[AlexWayfer]

Steps to reproduce

https://github.com/mdub/clamp/blob/2844879/lib/clamp/command.rb#L121-L126

Actual Output

https://rubydoc.info/gems/clamp/1.3.2/Clamp/Command

Expected Output

Methods from modules, included inside class << self, should be class methods, not instance.

Environment details:

I don't know about https://rubydoc.info/ environment.

[ForeverZer0]

In the given example, the #run and #execute methods are defined as both instance methods and then again in the Eigenclass.

Lines 64 and 73 are instance methods, which are what is being seen in the image above. The ones within the Eigenclass on lines 129 and 139 have different documentation that is not seen here, though should be as class methods, though the image is cropped.

I test ran on the given file to see the uncropped result, and they were included as both class and instance methods, which would the correct behavior for how the code is written.

[AlexWayfer]

@ForeverZer0 Thank you for your investigation, but this issue has nothing about execute or run.

I should highlight the problem place: "Methods included from %module_name%" below "Instance method summary", do you see it?

It should be in the class methods section for described case, when include inside class << self.

[ForeverZer0]

@AlexWayfer Ah, yes, I was misunderstanding what you were describing, but see now, my apologies.

[lsegal]

@AlexWayfer after looking into this, it's actually behaving as I believe you want it to, it's just not quite as visually clear as you might hope. This is a templating issue, not a data integrity issue. Let me explain:

When you see Methods included from ..., you actually are seeing these methods as class level methods. The distinction is subtle, but if these were instance methods, you would see the method names with # prefixes. For example, if I update Command to remove class << self on the includes, it looks like this:

The reason it looks like they are being treated as inherited methods is because YARD structures the sections in the default template using the following pseudo-markdown as a layout:

# Class Method Summary

* ...class methods here...

# Instance Method Summary

* ...instance methods here...

<METHODS INHERITED LIST PER MIXIN/SUPERCLASS>

There is no header separating the inherited methods list from the "Instance method summary" section, so it might seem like they are all instance methods. They are not. The list is generic, and the scope that they are inherited as depends on the formatting of the method (foo vs #foo). In other words, the "Methods inherited from X" can include both class and instance methods, it just so happens that your example does not. Here's a mock example of how that would look if you were including methods with both scopes:

In your case where there are only class methods being included, this is notably confusing. If someone opened a PR to make this less ambiguous in a way that respects the current layout, it would probably be incorporated-- help appreciated here. Of course, you can choose to modify YARD's templates to make this more clear in your own docs until this is released in YARD (though RubyDoc does not yet support rendering custom templates).

Finally, just to make this a little more clear that it's an information display issue and not an issue with parsing, you can see that YARD is treating these as class methods if you run YARD with --embed-mixins (yard doc --embed-mixins or add the flag to your .yardopts for rubydoc support):

FWIW, if you're relying on this inclusion pattern to expose methods, this flag might be what you want to better document the extended class methods as first-class citizens on the Command class, though this is technically unrelated to the reported issue.

[AlexWayfer]

@lsegal thank you for your overall response. I glad that there is no parsing issues. Yes, displaying can be improved. And --embed-mixins flag looks really nice (should I ask Ruby-Doc.info to use it? 🤔 rhetorical question).