Bug #10105

Mixed styles for class methods on Tempfile break RDocs.

Added by Eloy Esp 7 months ago. Updated 7 months ago.

[ruby-core:64157]
Status:Closed
Priority:Normal
Assignee:Zachary Scott
ruby -v:2.1.1 Backport:2.0.0: UNKNOWN, 2.1: UNKNOWN

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.

Associated revisions

Revision 47133
Added by Nobuyoshi Nakada 7 months ago

lib/tempfile.rb: include doc of Tempfile.open

  • lib/tempfile.rb: start rdoc parsing inside singleton class definition to include the document there. [Bug #10105]

Revision 47133
Added by Nobuyoshi Nakada 7 months ago

lib/tempfile.rb: include doc of Tempfile.open

  • lib/tempfile.rb: start rdoc parsing inside singleton class definition to include the document there. [Bug #10105]

History

#1 Updated by Nobuyoshi Nakada 7 months ago

  • Status changed from Open to Third Party's Issue
  • Assignee changed from Zachary Scott to Eric Hodel
  • Priority changed from Low to Normal

Rather I think it a bug of RDoc.

#2 Updated by Eloy Esp 7 months 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.

#3 Updated by Nobuyoshi Nakada 7 months ago

It's valid code, at least.
Whether you consider it a good example or not is another story.

#4 Updated by Zachary Scott 7 months ago

  • Assignee changed from Eric Hodel to Zachary Scott
  • 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:

See http://docs.seattlerb.org/rdoc/RDoc/Parser/Ruby.html#class-RDoc::Parser::Ruby-label-Metaprogrammed+Methods

Could you send a patch for this instead?

#5 Updated by Eloy Esp 7 months 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

#6 Updated by Nobuyoshi Nakada 7 months 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. [Bug #10105]

Also available in: Atom PDF