[DOC] Tweaks for GC.start (#14093)

gc.rb

@@ -7,31 +7,39 @@
 #  You may obtain information about the operation of the \GC through GC::Profiler.
 module GC
 
-  # Initiates garbage collection, even if manually disabled.
+  # Initiates garbage collection, even if explicitly disabled by GC.disable.
   #
-  # The +full_mark+ keyword argument determines whether or not to perform a
+  # Keyword arguments:
-  # major garbage collection cycle. When set to +true+, a major garbage
-  # collection cycle is run, meaning all objects are marked. When set to
-  # +false+, a minor garbage collection cycle is run, meaning only young
-  # objects are marked.
   #
-  # The +immediate_mark+ keyword argument determines whether or not to perform
+  # - +full_mark+:
-  # incremental marking. When set to +true+, marking is completed during the
+  #   its boolean value determines whether to perform a major garbage collection cycle:
-  # call to this method. When set to +false+, marking is performed in steps
-  # that are interleaved with future Ruby code execution, so marking might not
-  # be completed during this method call. Note that if +full_mark+ is +false+,
-  # then marking will always be immediate, regardless of the value of
-  # +immediate_mark+.
   #
-  # The +immediate_sweep+ keyword argument determines whether or not to defer
+  #   - +true+: initiates a major garbage collection cycle,
-  # sweeping (using lazy sweep). When set to +false+, sweeping is performed in
+  #     meaning all objects (old and new) are marked.
-  # steps that are interleaved with future Ruby code execution, so sweeping might
+  #   - +false+: initiates a minor garbage collection cycle,
-  # not be completed during this method call. When set to +true+, sweeping is
+  #     meaning only young objects are marked.
-  # completed during the call to this method.
   #
-  # Note: These keyword arguments are implementation and version-dependent. They
+  # - +immediate_mark+:
-  # are not guaranteed to be future-compatible and may be ignored if the
+  #   its boolean value determines whether to perform incremental marking:
-  # underlying implementation does not support them.
+  #
+  #   - +true+: marking is completed before the method returns.
+  #   - +false+: marking is performed by parts,
+  #     interleaved with program execution both before the method returns and afterward;
+  #     therefore marking may not be completed before the return.
+  #     Note that if +full_mark+ is +false+, marking will always be immediate,
+  #     regardless of the value of +immediate_mark+.
+  #
+  # - +immediate_sweep+:
+  #   its boolean value determines whether to defer sweeping (using lazy sweep):
+  #
+  #   - +true+: sweeping is completed before the method returns.
+  #   - +false+: sweeping is performed by parts,
+  #     interleaved with program execution both before the method returns and afterward;
+  #     therefore sweeping may not be completed before the return.
+  #
+  # Note that these keword arguments are implementation- and version-dependent,
+  # are not guaranteed to be future-compatible,
+  # and may be ignored in some implementations.
   def self.start full_mark: true, immediate_mark: true, immediate_sweep: true
     Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
   end