From: zverok.offline@... Date: 2020-12-22T06:44:34+00:00 Subject: [ruby-core:101624] [Ruby master Bug#17389] New docs for non-blocking Fibers and scheduler Issue #17389 has been updated by zverok (Victor Shepelev). @matz, can you please look into this question? @ioquatix have updated `scheduler.md`���`fiber.md` in https://github.com/ruby/ruby/pull/3965/files, where it now looks like a generic `Fiber` class docs, but I still believe the docs should be in the class itself, and that `Fiber::SchedulerInterface` is the right way to document how the scheduler is expected to work, which I propose in https://github.com/ruby/ruby/pull/3965/files and this ticket. TBH, I feel completely lost in regards to who's responsible for the documentation (besides each feature's author) and who should/want/can make decisions about it. ---------------------------------------- Bug #17389: New docs for non-blocking Fibers and scheduler https://bugs.ruby-lang.org/issues/17389#change-89416 * 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: