Misc #17422: 3.0 documentation problems tracking ticket

• Status: Closed
• Assignee: -

[zverok (Victor Shepelev)]

A meta-ticket for tracking all documentation problems with 3.0's new features (which hopefully should be fixed before the release). I plan to work on those myself, but I have only so much time, so the help would be appreciated.

• Missing docs for new methods:
  • Symbol#name, Proc#==, Fiber#backtrace (more or less trivial, handled by https://github.com/ruby/ruby/pull/3966) merged
• Method docs to be changed
  • Fiber#transfer changed limitations -- requires thorough redocumenting of #transfer, its use cases and limitations: https://github.com/ruby/ruby/pull/3981 merged
  • Module#include / #prepend -- I'd say the docs should be rewritten (now they are from the "internal" point of view), and only then there would be a place to describe the behavior change;
• Larger chunks:
  • doc/syntax/methods.rdoc -- no sign of ... or "endless" methods: https://github.com/ruby/ruby/pull/3997 to review
  • Fiber scheduler and non-blocking fibers: my take is https://github.com/ruby/ruby/pull/3891 / #17389, now it is up to @ioquatix (Samuel Williams) to accept/reject or do it his way merged
  • doc/syntax/pattern_matching.rdoc -- should be reviewed, cleaned up (at least formatting) and probably structured better after reintroduction of two kinds of one-line matching;
• Should it be updated?
  • doc/syntax/assignment.rdoc -- "Class Variable" section, include more explanation on visibility (and new exceptions on "overtaking")?
  • Kernel#lambda -- include info on "only literal blocks"?
  • Symbol#to_proc -- explain about the block's lambdiness?
  • Mutex -- mention it is owned per-Fiber?
• Documentation bugs:
  • Random lost definitions of instance methods: fixed by https://github.com/ruby/ruby/pull/3966 merged
  • Kernel: lost docs for several methods (like #abort, but also #exec, #exit) due to NO_RETURN macro, I am not yet sure how to fix it (moving comment before macro does not help)

To be continued...

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

Current status updated in ticket description. Of the critical (?) things before the release, I believe this is the most important:

• Kernel: lost docs for several methods (like #abort, but also #exec, #exit) due to NORETURN macro, I am not yet sure how to fix it (moving comment before macro does not help).

Could be related to this commit in RDoc: "Exclude parenthesized function declarations such as NORETURN"

cc @nobu (Nobuyoshi Nakada)

[nobu (Nobuyoshi Nakada)]

zverok (Victor Shepelev) wrote in #note-2:

• Kernel: lost docs for several methods (like #abort, but also #exec, #exit) due to NORETURN macro, I am not yet sure how to fix it (moving comment before macro does not help).

That page is generated by RDoc 6.2.1.

Could be related to this commit in RDoc: "Exclude parenthesized function declarations such as NORETURN"

Yes, it intends to fix that issue, but isn't contained in older released versions of course.

[zverok (Victor Shepelev)]

@nobu (Nobuyoshi Nakada) oh, good! I somehow assumed it always uses the rdoc bundled with the same version it documents.

[zverok (Victor Shepelev)]

• Status changed from Open to Closed