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

Description updated

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](https://docs.ruby-lang.org/en/master/Kernel.html#method-i-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"](https://github.com/ruby/rdoc/commit/1f059d6954f9652e4ac73893b33efd1e53921edb)

cc @nobu

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

* 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)~~ **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 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](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>