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


@hakusaro This all would be (somewhat) true if I'd demanded "do document that new feature".
But I did it myself, I just asked if somebody can _review_ the docs (done since my last comment by @marcandre, huge thanks!)

Overall, I don't think the "everyone is too busy right now and docs aren't that important" attitude is a good thing for a major public release of the popular programming language...

Honestly, I feel like Ruby really needs some "documentation working group" to manage this aspect.

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

* 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:ruby-core-request / ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>