[ruby-core:101430] [Ruby master Bug#17389] New docs for non-blocking Fibers and scheduler

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

----------------------------------------
Bug #17389: New docs for non-blocking Fibers and scheduler 
https://bugs.ruby-lang.org/issues/17389

* Author: zverok (Victor Shepelev)
* Status: Open
* Priority: Normal
* Backport: 2.5: UNKNOWN, 2.6: UNKNOWN, 2.7: UNKNOWN
----------------------------------------
**GitHub PR: https://github.com/ruby/ruby/pull/3891**

Copying from its description:

I propose new documentation approach for new features in Ruby 3.0: non-blocking Fiber and the scheduler.

Right now, the documentation is in a confusing state. First, the `doc/scheduler.md` is even not rendered correclty: https://docs.ruby-lang.org/en/master/doc/scheduler_md.html (relatively easy to fix: wrong markdown markup for the code-blocks), and Fiber class itself has no mention for new concepts, and no docs for new methods: https://docs.ruby-lang.org/en/master/Fiber.html#method-c-schedule.

But on the bigger level, the documentation is quite hard to follow unless you are already fully in context of asynchronous loops and schedulers.

I am trying to fix it by:

* adding to the `Fiber` class necessary docs, both high-level overview and particular method details
* redocumenting the expected scheduler interface via "imaginary" `Fiber::SchedulerInterface` class: it is present only in docs to leverage RDoc's method-by-method documentation, be able to link to them separately and so on

Test rendering of the docs on my personal site:

* [Fiber](https://zverok.github.io/ruby-rdoc/Fiber.html)
* [Fiber::SchedulerInterface](https://zverok.github.io/ruby-rdoc/Fiber/SchedulerInterface.html)

I have not yet in this PR removed doc/scheduler.md, but I suggest to, as it is completely superseded by new docs.

I'd be really grateful if @ioquatix will find some time to review this initiative in the upcoming days.



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

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