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) about 10 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) about 10 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) about 10 years ago
It's valid code, at least.
Whether you consider it a good example or not is another story.
Updated by zzak (zzak _) about 10 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) about 10 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) about 10 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]