Issue #17422 has been reported by zverok (Victor Shepelev).

----------------------------------------
Misc #17422: 3.0 documentation problems tracking ticket
https://bugs.ruby-lang.org/issues/17422

* Author: zverok (Victor Shepelev)
* Status: Open
* Priority: Normal
----------------------------------------
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)
* Method docs to be changed
  * `Fiber#transfer` changed limitations -- requires thorough redocumenting of `#transfer`, its use cases and limitations
  * `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/pattern_matching.rdoc` -- should be reviewed, cleaned up (at least formatting) and probably structured better after reintroduction of two kinds of one-line matching;
  * `doc/syntax/methods.rdoc` -- no sign of `...` or "endless" methods
  * Fiber scheduler and non-blocking fibers: my take is https://github.com/ruby/ruby/pull/3891 / #17389, now it is up to @ioquatix to accept/reject or do it his way
* 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
  * `Kernel`: lost docs for several methods (like [#abort](https://docs.ruby-lang.org/en/master/Kernel.html#method-i-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...



-- 
https://bugs.ruby-lang.org/

Unsubscribe: <mailto:ruby-core-request / ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>