Misc #19247: Ruby 3.2 documentation problems tracker

• Status: Closed
• Assignee: zverok (Victor Shepelev)

[zverok (Victor Shepelev)]

Bugs and problems:

• Fiber:
  • Formatting glitches for ::[], ::[]=, ::storage, ::storage= (no references to companion methods)
  • Also there are some rendering glitches in Fiber, due to RDoc update? (Source didn't change)
  • After renaming SchedulerInterface to Scheduler, reference to it from Fiber are lost
• FiberScheduler has no docs for new method #io_select
• SyntaxError: new attribute #path wrongly rendered
• RubyVM::AbstractSyntaxTree: error_tolerant: and keep_tokens: options aren't documented or mentioned in the docs
• Set: docs still start with require 'set' :)
• Struct: no mention of the changed requirement about keyword initialization.
• Time#deconstruct_keys instead of listing keys refers to "the same as returned by to_h", which we decided not to implement, my bad!
• UnboundMethod#== says that methods are equal if are bound to the same object :) (shares docs with Method?..)
• GC::latest_gc_info rendering glitch (old probably). It also lacks any docs about the structure of the hash returned.
• ObjectSpace.dump_all and several companion methods are weirdly documented as instance methods (RDoc glitch, doubtfully easy to fix)

Things that could be improved:

• Module#undefined_instance_methods is not really helpful :)
• Refinement#refined_class can use better explanation/example?
• Thread::each_caller_location can use an example? (Also wrongly referred as instance method in NEWS)

I'll try to work on those ASAP.

UPD 2022-12-21:

• IO#Open Options don't mention path:.

[zverok (Victor Shepelev)]

https://github.com/ruby/ruby/pull/6985 Fixes:

• Fiber
• SyntaxError
• Struct
• Time
• UnboundMethod
• GC

I plan to do at least two more before the release:

• One documenting all the changes in Fiber::Scheduler and IOBuffer
• One documenting AbstractSyntaxTree options and behaviors (besides new options for initialize, there are new methods in Node, and some were missed in 3.0, too)
• (Maybe) One with wording/examples improvement for newly introduced methods, where it is not critical.

[zverok (Victor Shepelev)]

• Description updated (diff)

Just discovered one more: IO#Open Options don't mention path:.

[zverok (Victor Shepelev)]

https://github.com/ruby/ruby/pull/6996 adds missing AST keyword arguments docs.

[zverok (Victor Shepelev)]

https://github.com/ruby/ruby/pull/7016 Fiber::Scheduler and IO::Buffer missing methods.

@jeremyevans0 (Jeremy Evans) sorry, I tagged you in both, you are usually the quickest to respond, and time is tight 🙏

Next year, I plan to follow the development with my changelog and doc fixes throughout the year instead of trying to squeeze it all in December.

[zverok (Victor Shepelev)]

• Status changed from Open to Closed

I did what I could before the release, the other problems can be handled separately through the year.