Bug #10105
closedMixed styles for class methods on Tempfile break RDocs.
Description
I've already made a little pull request here https://github.com/ruby/ruby/pull/691.
The diff is here: https://github.com/ruby/ruby/pull/691.diff
But to make the real changes clear is it better to ignore white-space (as there are many indentation changes).
Changes ignoring white-space: https://github.com/ruby/ruby/pull/691/files?w=1
Regards.
Updated by nobu (Nobuyoshi Nakada) over 9 years ago
- Status changed from Open to Third Party's Issue
- Assignee changed from zzak (zzak _) to drbrain (Eric Hodel)
- Priority changed from 3 to Normal
Rather I think it a bug of RDoc.
Updated by eloyesp (Eloy Esp) over 9 years ago
I don't think that it is only a bug in RDoc.
There are at least 3 ways to define class methods in ruby, and I think that all are acceptable, but define two class methods in different ways in the standard library it's not a good example, nor a good practice and does not help in readability.
Ok, there is a lacking feature in RDoc, but I don't think that keeping it that way is the way to go.
Updated by nobu (Nobuyoshi Nakada) over 9 years ago
It's valid code, at least.
Whether you consider it a good example or not is another story.
Updated by zzak (zzak _) over 9 years ago
- Assignee changed from drbrain (Eric Hodel) to zzak (zzak _)
- Status changed from Third Party's Issue to Assigned
This may be a bug in RDoc, but we can fix it without redefining the methods by using the document method directive:
Could you send a patch for this instead?
Updated by eloyesp (Eloy Esp) over 9 years ago
I've tried to fix it only touching documentation, and it seems to be
impossible, rdoc does not understand the class << self
syntax (I
understand rdoc in this point, ruby is not easy to parse). I've added an
issue in Rdoc for it ( https://github.com/rdoc/rdoc/issues/317 ).
So the Tempfile.open method needs to be redefined to be understand by rdoc.
I've updated the pull request with the minimal change that will fix the
issue I don't like it as it define class methods outside of the class
itself (so the source is harder to read), and it hardcode the class name
two times (that I think is ugly).
I quite not understand why there is so much resistance to refactor the code
for readability.
--- Eloy
Updated by nobu (Nobuyoshi Nakada) over 9 years ago
- Status changed from Assigned to Closed
- % Done changed from 0 to 100
Applied in changeset r47133.
lib/tempfile.rb: include doc of Tempfile.open
- lib/tempfile.rb: start rdoc parsing inside singleton class
definition to include the document there.
[ruby-core:64157] [Bug #10105]