Misc #17422
Updated by zverok (Victor Shepelev) over 3 years ago
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`, `Symbol#name`, `Proc#==`, `Fiber#backtrace` (more or less trivial, handled by https://github.com/ruby/ruby/pull/3966)~~ **merged** 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: https://github.com/ruby/ruby/pull/3981 **to review** 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 **to review** * `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` `Random` lost definitions of instance methods: fixed by https://github.com/ruby/ruby/pull/3966~~ **merged** 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...