Docs: Fix problems with Fiber's docs

zverok · zverok · commit bc3d9021d997 · 2022-12-21T22:10:21.000+02:00
* References to Scheduler (was outdated to SchedulerInterface)
* References between new methods (storage, [], []=)
* Storage's call-sequence (rendered confusingly)
diff --git a/cont.c b/cont.c
@@ -1959,7 +1959,7 @@ rb_cont_call(int argc, VALUE *argv, VALUE contval)
  *  the current thread, blocking and non-blocking fibers' behavior is identical.
  *
  *  Ruby doesn't provide a scheduler class: it is expected to be implemented by
- *  the user and correspond to Fiber::SchedulerInterface.
+ *  the user and correspond to Fiber::Scheduler.
  *
  *  There is also Fiber.schedule method, which is expected to immediately perform
  *  the given block in a non-blocking manner. Its actual implementation is up to
@@ -2080,9 +2080,10 @@ storage_access_must_be_from_same_fiber(VALUE self)
 }
 
 /**
- *  call-seq: Fiber.current.storage -> hash (dup)
+ *  call-seq: fiber.storage -> hash (dup)
  *
- *  Returns a copy of the storage hash for the current fiber.
+ *  Returns a copy of the storage hash for the fiber. The method can only be called on the
+ *  Fiber.current.
  */
 static VALUE
 rb_fiber_storage_get(VALUE self)
@@ -2117,16 +2118,17 @@ fiber_storage_validate(VALUE value)
 }
 
 /**
- *  call-seq: Fiber.current.storage = hash
+ *  call-seq: fiber.storage = hash
  *
- *  Sets the storage hash for the current fiber. This feature is experimental
- *  and may change in the future.
+ *  Sets the storage hash for the fiber. This feature is experimental
+ *  and may change in the future. The method can only be called on the
+ *  Fiber.current.
  *
  *  You should be careful about using this method as you may inadvertently clear
  *  important fiber-storage state. You should mostly prefer to assign specific
- *  keys in the storage using Fiber#[]=.
+ *  keys in the storage using Fiber::[]=.
  *
- *  You can also use Fiber.new(storage: nil) to create a fiber with an empty
+ *  You can also use <tt>Fiber.new(storage: nil)</tt> to create a fiber with an empty
  *  storage.
  *
  *  Example:
@@ -2160,7 +2162,7 @@ rb_fiber_storage_set(VALUE self, VALUE value)
  *  The +key+ must be a symbol, and the value is set by Fiber#[]= or
  *  Fiber#store.
  *
- *  See also Fiber[]=.
+ *  See also Fiber::[]=.
  */
 static VALUE
 rb_fiber_storage_aref(VALUE class, VALUE key)
@@ -2183,7 +2185,7 @@ rb_fiber_storage_aref(VALUE class, VALUE key)
  *
  *  +key+ must be a Symbol, otherwise a TypeError is raised.
  *
- *  See also Fiber[].
+ *  See also Fiber::[].
  */
 static VALUE
 rb_fiber_storage_aset(VALUE class, VALUE key, VALUE value)
@@ -2397,7 +2399,7 @@ rb_fiber_s_schedule_kw(int argc, VALUE* argv, int kw_splat)
  *
  *  Note that the behavior described above is how the method is <em>expected</em>
  *  to behave, actual behavior is up to the current scheduler's implementation of
- *  Fiber::SchedulerInterface#fiber method. Ruby doesn't enforce this method to
+ *  Fiber::Scheduler#fiber method. Ruby doesn't enforce this method to
  *  behave in any particular way.
  *
  *  If the scheduler is not set, the method raises
@@ -2416,7 +2418,7 @@ rb_fiber_s_schedule(int argc, VALUE *argv, VALUE obj)
  *
  *  Returns the Fiber scheduler, that was last set for the current thread with Fiber.set_scheduler.
  *  Returns +nil+ if no scheduler is set (which is the default), and non-blocking fibers'
- #  behavior is the same as blocking.
+ *  behavior is the same as blocking.
  *  (see "Non-blocking fibers" section in class docs for details about the scheduler concept).
  *
  */
@@ -2450,7 +2452,7 @@ rb_fiber_current_scheduler(VALUE klass)
  *  thread will call scheduler's +close+ method on finalization (allowing the scheduler to
  *  properly manage all non-finished fibers).
  *
- *  +scheduler+ can be an object of any class corresponding to Fiber::SchedulerInterface. Its
+ *  +scheduler+ can be an object of any class corresponding to Fiber::Scheduler. Its
  *  implementation is up to the user.
  *
  *  See also the "Non-blocking fibers" section in class docs.

Original file line number	Diff line number	Diff line change
`@@ -1959,7 +1959,7 @@ rb_cont_call(int argc, VALUE *argv, VALUE contval)`
`1959`	`1959`	`* the current thread, blocking and non-blocking fibers' behavior is identical.`
`1960`	`1960`	`*`
`1961`	`1961`	`* Ruby doesn't provide a scheduler class: it is expected to be implemented by`
`1962`		`- * the user and correspond to Fiber::SchedulerInterface.`
	`1962`	`+ * the user and correspond to Fiber::Scheduler.`
`1963`	`1963`	`*`
`1964`	`1964`	`* There is also Fiber.schedule method, which is expected to immediately perform`
`1965`	`1965`	`* the given block in a non-blocking manner. Its actual implementation is up to`
`@@ -2080,9 +2080,10 @@ storage_access_must_be_from_same_fiber(VALUE self)`
`2080`	`2080`	`}`
`2081`	`2081`
`2082`	`2082`	`/**`
`2083`		`- * call-seq: Fiber.current.storage -> hash (dup)`
	`2083`	`+ * call-seq: fiber.storage -> hash (dup)`
`2084`	`2084`	`*`
`2085`		`- * Returns a copy of the storage hash for the current fiber.`
	`2085`	`+ * Returns a copy of the storage hash for the fiber. The method can only be called on the`
	`2086`	`+ * Fiber.current.`
`2086`	`2087`	`*/`
`2087`	`2088`	`static VALUE`
`2088`	`2089`	`rb_fiber_storage_get(VALUE self)`
`@@ -2117,16 +2118,17 @@ fiber_storage_validate(VALUE value)`
`2117`	`2118`	`}`
`2118`	`2119`
`2119`	`2120`	`/**`
`2120`		`- * call-seq: Fiber.current.storage = hash`
	`2121`	`+ * call-seq: fiber.storage = hash`
`2121`	`2122`	`*`
`2122`		`- * Sets the storage hash for the current fiber. This feature is experimental`
`2123`		`- * and may change in the future.`
	`2123`	`+ * Sets the storage hash for the fiber. This feature is experimental`
	`2124`	`+ * and may change in the future. The method can only be called on the`
	`2125`	`+ * Fiber.current.`
`2124`	`2126`	`*`
`2125`	`2127`	`* You should be careful about using this method as you may inadvertently clear`
`2126`	`2128`	`* important fiber-storage state. You should mostly prefer to assign specific`
`2127`		`- * keys in the storage using Fiber#[]=.`
	`2129`	`+ * keys in the storage using Fiber::[]=.`
`2128`	`2130`	`*`
`2129`		`- * You can also use Fiber.new(storage: nil) to create a fiber with an empty`
	`2131`	`+ * You can also use <tt>Fiber.new(storage: nil)</tt> to create a fiber with an empty`
`2130`	`2132`	`* storage.`
`2131`	`2133`	`*`
`2132`	`2134`	`* Example:`
`@@ -2160,7 +2162,7 @@ rb_fiber_storage_set(VALUE self, VALUE value)`
`2160`	`2162`	`* The +key+ must be a symbol, and the value is set by Fiber#[]= or`
`2161`	`2163`	`* Fiber#store.`
`2162`	`2164`	`*`
`2163`		`- * See also Fiber[]=.`
	`2165`	`+ * See also Fiber::[]=.`
`2164`	`2166`	`*/`
`2165`	`2167`	`static VALUE`
`2166`	`2168`	`rb_fiber_storage_aref(VALUE class, VALUE key)`
`@@ -2183,7 +2185,7 @@ rb_fiber_storage_aref(VALUE class, VALUE key)`
`2183`	`2185`	`*`
`2184`	`2186`	`* +key+ must be a Symbol, otherwise a TypeError is raised.`
`2185`	`2187`	`*`
`2186`		`- * See also Fiber[].`
	`2188`	`+ * See also Fiber::[].`
`2187`	`2189`	`*/`
`2188`	`2190`	`static VALUE`
`2189`	`2191`	`rb_fiber_storage_aset(VALUE class, VALUE key, VALUE value)`
`@@ -2397,7 +2399,7 @@ rb_fiber_s_schedule_kw(int argc, VALUE* argv, int kw_splat)`
`2397`	`2399`	`*`
`2398`	`2400`	`* Note that the behavior described above is how the method is <em>expected</em>`
`2399`	`2401`	`* to behave, actual behavior is up to the current scheduler's implementation of`
`2400`		`- * Fiber::SchedulerInterface#fiber method. Ruby doesn't enforce this method to`
	`2402`	`+ * Fiber::Scheduler#fiber method. Ruby doesn't enforce this method to`
`2401`	`2403`	`* behave in any particular way.`
`2402`	`2404`	`*`
`2403`	`2405`	`* If the scheduler is not set, the method raises`
`@@ -2416,7 +2418,7 @@ rb_fiber_s_schedule(int argc, VALUE *argv, VALUE obj)`
`2416`	`2418`	`*`
`2417`	`2419`	`* Returns the Fiber scheduler, that was last set for the current thread with Fiber.set_scheduler.`
`2418`	`2420`	`* Returns +nil+ if no scheduler is set (which is the default), and non-blocking fibers'`
`2419`		`- # behavior is the same as blocking.`
	`2421`	`+ * behavior is the same as blocking.`
`2420`	`2422`	`* (see "Non-blocking fibers" section in class docs for details about the scheduler concept).`
`2421`	`2423`	`*`
`2422`	`2424`	`*/`
`@@ -2450,7 +2452,7 @@ rb_fiber_current_scheduler(VALUE klass)`
`2450`	`2452`	`* thread will call scheduler's +close+ method on finalization (allowing the scheduler to`
`2451`	`2453`	`* properly manage all non-finished fibers).`
`2452`	`2454`	`*`
`2453`		`- * +scheduler+ can be an object of any class corresponding to Fiber::SchedulerInterface. Its`
	`2455`	`+ * +scheduler+ can be an object of any class corresponding to Fiber::Scheduler. Its`
`2454`	`2456`	`* implementation is up to the user.`
`2455`	`2457`	`*`
`2456`	`2458`	`* See also the "Non-blocking fibers" section in class docs.`