[ruby-core:101438] [Ruby master Misc#17390] Class and method-level docs for Ractor

[ruby-core:101438] [Ruby master Misc#17390] Class and method-level docs for Ractor

[zverok.offline]

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

----------------------------------------
Misc #17390: Class and method-level docs for Ractor
https://bugs.ruby-lang.org/issues/17390

* Author: zverok (Victor Shepelev)
* Status: Open
* Priority: Normal
----------------------------------------
**GitHub PR: https://github.com/ruby/ruby/pull/3895**

Copying from PR descriptioin:

Currently, ractors documented only by [doc/ractor.md](https://docs.ruby-lang.org/en/master/doc/ractor_md.html), which has a flavor of a design/discussion document. I wanted to establish some _base_ documentation, which will allow to understand and use the concept immediately. Currently, Ractor class [has no docs at all](https://docs.ruby-lang.org/en/master/Ractor.html) -- it is partially due to the fact that `ractor.rb` is not included in the `.document` list for RDoc, but even so, per-method [docs in ractor.rb](https://github.com/ruby/ruby/blob/master/ractor.rb) seem kinda sparse and chaotic to me.

I've completely rewritten the class docs. They are now somewhat duplicating `doc/ractor.md`, but from a different perspective.

Test rendering of the docs on my personal site: [Ractor.html](https://zverok.github.io/ruby-rdoc/Ractor.html)

@ko1 @marcandre @eregon Can you please review it?

And one question I couldn't clarify by myself: can somebody please show an example of the code throwing `Ractor::UnsafeError` and maybe provide some brief explanation about it?.. From the sources I kinda get the idea, but my knowledge is not deep enough.



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