Tweak docs for Fiber::ExecutionContext [fixup #16135] (#16196)

Co-authored-by: Johannes Müller <[email protected]>

Author: ysbaddaden

src/fiber/execution_context.cr

@@ -37,11 +37,11 @@ require "./execution_context/*"
 # for common use cases.
 #
 # * `ExecutionContext::Concurrent`: Fully concurrent with limited parallelism.
-# Fibers run concurrently, never in parallel (only one fiber at a time). They
-# can use simpler and faster synchronization primitives internally (no atomics,
-# limited thread safety). Communication with fibers in other contexts requires
-# thread-safe primitives. A blocking fiber blocks the entire thread and all
-# other fibers in the context.
+# Fibers run concurrently to each other, never in parallel (only one fiber at a
+# time). They can use simpler and faster synchronization primitives internally
+# (no atomics, limited thread safety). Communication with fibers in other
+# contexts requires thread-safe primitives. A blocking fiber blocks the entire
+# thread and all other fibers in the context.
 # * `ExecutionContext::Parallel`: Fully concurrent, fully parallel. Fibers
 # running in this context can be resumed by multiple system threads in this
 # context. They run concurrently and in parallel to each other (multiple fibers
@@ -73,6 +73,10 @@ module Fiber::ExecutionContext
 
   # Returns the default `ExecutionContext` for the process, automatically
   # started when the program started.
+  #
+  # The default execution context is currently `Parallel` but only starts with
+  # parallelism set to 1. The parallelism can be changed using
+  # `Parallel#resize`.
   @[AlwaysInline]
   def self.default : ExecutionContext
     @@default.not_nil!("expected default execution context to have been setup")
@@ -163,8 +167,7 @@ module Fiber::ExecutionContext
     end
   end
 
-  # Creates a new fiber then calls `#enqueue` to add it to the execution
-  # context.
+  # Creates a new fiber then calls enqueues it to the execution context.
   #
   # May be called from any `ExecutionContext` (i.e. must be thread-safe).
   def spawn(*, name : String? = nil, &block : ->) : Fiber

src/fiber/execution_context/concurrent.cr

@@ -13,8 +13,8 @@ module Fiber::ExecutionContext
   # communication with fibers in other contexts requires safe primitives, for
   # example `Channel`.
   #
-  # A blocking fiber blocks the entire context, and thus all the
-  # other fibers in the context.
+  # A blocking fiber blocks the entire context, and thus all the other fibers in
+  # the context.
   #
   # For example: we can start a concurrent context to run consumer fibers, while
   # the default context produces values. Because the consumer fibers will never
@@ -54,14 +54,19 @@ module Fiber::ExecutionContext
   # variable, for example using `Atomic#add` to increment *result* or a `Mutex`
   # for more complex operations.
   class Concurrent < Parallel
+    # :nodoc:
     def self.default : self
       new("DEFAULT", capacity: 1, hijack: true)
     end
 
+    # Creates a `Concurrent` context. The context will only really start when a
+    # fiber is spawned into it.
     def self.new(name : String) : self
       new(name, capacity: 1, hijack: false)
     end
 
+    # Always raises an `ArgumentError` exception because a concurrent context
+    # cannot be resized.
     def resize(maximum : Int32) : Nil
       raise ArgumentError.new("Can't resize a concurrent context")
     end

src/fiber/execution_context/parallel.cr

@@ -79,10 +79,10 @@ module Fiber::ExecutionContext
       new("DEFAULT", maximum, hijack: true)
     end
 
-    # Starts a context with a *maximum* parallelism. The context starts with an
-    # initial parallelism of zero. It will grow to one when a fiber is spawned,
-    # then the actual parallelism will keep increasing and decreasing as needed,
-    # but will never go past the configured *maximum*.
+    # Starts a `Parallel` context with a *maximum* parallelism. The context
+    # starts with an initial parallelism of zero. It will grow to one when a
+    # fiber is spawned, then the actual parallelism will keep increasing and
+    # decreasing as needed, but will never go past the configured *maximum*.
     def self.new(name : String, maximum : Int32) : self
       new(name, maximum, hijack: false)
     end