[DOC] Repair format of What's Here sections in object.c (#5722)

* Repair format of What's Here sections in object.c

1 files changed, 147 insertions, 155 deletions

diff --git a/object.c b/object.c
index f6736fbe8b..8d5ab63c9c 100644
--- a/object.c
+++ b/object.c
@@ -4194,23 +4194,16 @@ f_sprintf(int c, const VALUE *v, VALUE _)
  *
  *  These are the methods defined for \BasicObject:
  *
- *  - ::new:: Returns a new \BasicObject instance.
- *  - #!:: Returns the boolean negation of +self+: +true+ or +false+.
- *  - #!=:: Returns whether +self+ and the given object are _not_ equal.
- *  - #==:: Returns whether +self+ and the given object are equivalent.
- *  - {__id__}[#method-i-__id__]:: Returns the integer object identifier for +self+.
- *  - {__send__}[#method-i-__send__]:: Calls the method identified by the given symbol.
- *  - #equal?:: Returns whether +self+ and the given object are the same object.
- *  - #instance_eval:: Evaluates the given string or block in the context of +self+.
- *  - #instance_exec:: Executes the given block in the context of +self+,
- *                     passing the given arguments.
- *  - #method_missing:: Method called when an undefined method is called on +self+.
- *  - #singleton_method_added:: Method called when a singleton method
- *                              is added to +self+.
- *  - #singleton_method_removed:: Method called when a singleton method
- *                                is added removed from +self+.
- *  - #singleton_method_undefined:: Method called when a singleton method
- *                                  is undefined in +self+.
+ *  - ::new: Returns a new \BasicObject instance.
+ *  - {!}[#method-i-21]: Returns the boolean negation of +self+: +true+ or +false+.
+ *  - {!=}[#method-i-21-3D]: Returns whether +self+ and the given object are _not_ equal.
+ *  - #==: Returns whether +self+ and the given object are equivalent.
+ *  - {__id__}[#method-i-__id__]: Returns the integer object identifier for +self+.
+ *  - {__send__}[#method-i-__send__]: Calls the method identified by the given symbol.
+ *  - #equal?: Returns whether +self+ and the given object are the same object.
+ *  - #instance_eval: Evaluates the given string or block in the context of +self+.
+ *  - #instance_exec: Executes the given block in the context of +self+,
+ *    passing the given arguments.
  *
  */
 
@@ -4247,72 +4240,72 @@ f_sprintf(int c, const VALUE *v, VALUE _)
  *
  *  === Querying
  *
- *  - #!~:: Returns +true+ if +self+ does not match the given object,
- *          otherwise +false+.
- *  - #<=>:: Returns 0 if +self+ and the given object +object+ are the same
- *           object, or if <tt>self == object</tt>; otherwise returns +nil+.
- *  - #===:: Implements case equality, effectively the same as calling #==.
- *  - #eql?:: Implements hash equality, effectively the same as calling #==.
- *  - #kind_of? (aliased as #is_a?):: Returns whether given argument is an ancestor
- *                                    of the singleton class of +self+.
- *  - #instance_of?:: Returns whether +self+ is an instance of the given class.
- *  - #instance_variable_defined?:: Returns whether the given instance variable
- *                                  is defined in +self+.
- *  - #method:: Returns the Method object for the given method in +self+.
- *  - #methods:: Returns an array of symbol names of public and protected methods
- *               in +self+.
- *  - #nil?:: Returns +false+. (Only +nil+ responds +true+ to method <tt>nil?</tt>.)
- *  - #object_id:: Returns an integer corresponding to +self+ that is unique
- *                 for the current process
- *  - #private_methods:: Returns an array of the symbol names
- *                       of the private methods in +self+.
- *  - #protected_methods:: Returns an array of the symbol names
- *                         of the protected methods in +self+.
- *  - #public_method:: Returns the Method object for the given public method in +self+.
- *  - #public_methods:: Returns an array of the symbol names
- *                      of the public methods in +self+.
- *  - #respond_to?:: Returns whether +self+ responds to the given method.
- *  - #singleton_class:: Returns the singleton class of +self+.
- *  - #singleton_method:: Returns the Method object for the given singleton method
- *                        in +self+.
- *  - #singleton_methods:: Returns an array of the symbol names
- *                         of the singleton methods in +self+.
- *
- *  - #define_singleton_method:: Defines a singleton method in +self+
- *                               for the given symbol method-name and block or proc.
- *  - #extend:: Includes the given modules in the singleton class of +self+.
- *  - #public_send:: Calls the given public method in +self+ with the given argument.
- *  - #send:: Calls the given method in +self+ with the given argument.
+ *  - {!~}[#method-i-21~]: Returns +true+ if +self+ does not match the given object,
+ *    otherwise +false+.
+ *  - {<=>}[#method-i-3C-3D-3E]: Returns 0 if +self+ and the given object +object+ are the same
+ *    object, or if <tt>self == object</tt>; otherwise returns +nil+.
+ *  - #===: Implements case equality, effectively the same as calling #==.
+ *  - #eql?: Implements hash equality, effectively the same as calling #==.
+ *  - #kind_of? (aliased as #is_a?): Returns whether given argument is an ancestor
+ *    of the singleton class of +self+.
+ *  - #instance_of?: Returns whether +self+ is an instance of the given class.
+ *  - #instance_variable_defined?: Returns whether the given instance variable
+ *    is defined in +self+.
+ *  - #method: Returns the Method object for the given method in +self+.
+ *  - #methods: Returns an array of symbol names of public and protected methods
+ *    in +self+.
+ *  - #nil?: Returns +false+. (Only +nil+ responds +true+ to method <tt>nil?</tt>.)
+ *  - #object_id: Returns an integer corresponding to +self+ that is unique
+ *    for the current process
+ *  - #private_methods: Returns an array of the symbol names
+ *    of the private methods in +self+.
+ *  - #protected_methods: Returns an array of the symbol names
+ *    of the protected methods in +self+.
+ *  - #public_method: Returns the Method object for the given public method in +self+.
+ *  - #public_methods: Returns an array of the symbol names
+ *    of the public methods in +self+.
+ *  - #respond_to?: Returns whether +self+ responds to the given method.
+ *  - #singleton_class: Returns the singleton class of +self+.
+ *  - #singleton_method: Returns the Method object for the given singleton method
+ *    in +self+.
+ *  - #singleton_methods: Returns an array of the symbol names
+ *    of the singleton methods in +self+.
+ *
+ *  - #define_singleton_method: Defines a singleton method in +self+
+ *    for the given symbol method-name and block or proc.
+ *  - #extend: Includes the given modules in the singleton class of +self+.
+ *  - #public_send: Calls the given public method in +self+ with the given argument.
+ *  - #send: Calls the given method in +self+ with the given argument.
  *
  *  === Instance Variables
  *
- *  - #instance_variable_get:: Returns the value of the given instance variable
- *                             in +self+, or +nil+ if the instance variable is not set.
- *  - #instance_variable_set:: Sets the value of the given instance variable in +self+
- *                             to the given object.
- *  - #instance_variables:: Returns an array of the symbol names
- *                          of the instance variables in +self+.
- *  - #remove_instance_variable:: Removes the named instance variable from +self+.
+ *  - #instance_variable_get: Returns the value of the given instance variable
+ *    in +self+, or +nil+ if the instance variable is not set.
+ *  - #instance_variable_set: Sets the value of the given instance variable in +self+
+ *    to the given object.
+ *  - #instance_variables: Returns an array of the symbol names
+ *    of the instance variables in +self+.
+ *  - #remove_instance_variable: Removes the named instance variable from +self+.
  *
  *  === Other
  *
- *  - #clone::  Returns a shallow copy of +self+, including singleton class
- *              and frozen state.
- *  - #define_singleton_method:: Defines a singleton method in +self+
- *                               for the given symbol method-name and block or proc.
- *  - #display:: Prints +self+ to the given \IO stream or <tt>$stdout</tt>.
- *  - #dup:: Returns a shallow unfrozen copy of +self+.
- *  - #enum_for (aliased as #to_enum):: Returns an Enumerator for +self+
- *                                      using the using the given method,
- *                                      arguments, and block.
- *  - #extend:: Includes the given modules in the singleton class of +self+.
- *  - #freeze:: Prevents further modifications to +self+.
- *  - #hash:: Returns the integer hash value for +self+.
- *  - #inspect:: Returns a human-readable  string representation of +self+.
- *  - #itself:: Returns +self+.
- *  - #public_send:: Calls the given public method in +self+ with the given argument.
- *  - #send:: Calls the given method in +self+ with the given argument.
- *  - #to_s:: Returns a string representation of +self+.
+ *  - #clone:  Returns a shallow copy of +self+, including singleton class
+ *    and frozen state.
+ *  - #define_singleton_method: Defines a singleton method in +self+
+ *    for the given symbol method-name and block or proc.
+ *  - #display: Prints +self+ to the given \IO stream or <tt>$stdout</tt>.
+ *  - #dup: Returns a shallow unfrozen copy of +self+.
+ *  - #enum_for (aliased as #to_enum): Returns an Enumerator for +self+
+ *    using the using the given method, arguments, and block.
+ *  - #extend: Includes the given modules in the singleton class of +self+.
+ *  - #freeze: Prevents further modifications to +self+.
+ *  - #hash: Returns the integer hash value for +self+.
+ *  - #inspect: Returns a human-readable  string representation of +self+.
+ *  - #itself: Returns +self+.
+ *  - #method_missing: Method called when an undefined method is called on +self+.
+ *  - #public_send: Calls the given public method in +self+ with the given argument.
+ *  - #send: Calls the given method in +self+ with the given argument.
+ *  - #to_s: Returns a string representation of +self+.
  *
  */
 
@@ -4392,118 +4385,117 @@ InitVM_Object(void)
      *
      * === Converting
      *
-     * - #Array:: Returns an Array based on the given argument.
-     * - #Complex:: Returns a Complex based on the given arguments.
-     * - #Float:: Returns a Float based on the given arguments.
-     * - #Hash:: Returns a Hash based on the given argument.
-     * - #Integer:: Returns an Integer based on the given arguments.
-     * - #Rational:: Returns a Rational based on the given arguments.
-     * - #String:: Returns a String based on the given argument.
+     * - #Array: Returns an Array based on the given argument.
+     * - #Complex: Returns a Complex based on the given arguments.
+     * - #Float: Returns a Float based on the given arguments.
+     * - #Hash: Returns a Hash based on the given argument.
+     * - #Integer: Returns an Integer based on the given arguments.
+     * - #Rational: Returns a Rational based on the given arguments.
+     * - #String: Returns a String based on the given argument.
      *
      * === Querying
      *
-     * - {#__callee__}[#method-i-__callee__]:: Returns the called name
-     *                                         of the current method as a symbol.
-     * - {#__dir__}[#method-i-__dir__]:: Returns the path to the directory
-     *                                   from which the current method is called.
-     * - {#__method__}[#method-i-__method__]:: Returns the name
-     *                                         of the current method as a symbol.
-     * - #autoload?:: Returns the file to be loaded when the given module is referenced.
-     * - #binding:: Returns a Binding for the context at the point of call.
-     * - #block_given?:: Returns +true+ if a block was passed to the calling method.
-     * - #caller:: Returns the current execution stack as an array of strings.
-     * - #caller_locations:: Returns the current execution stack as an array
-     *                       of Thread::Backtrace::Location objects.
-     * - #class:: Returns the class of +self+.
-     * - #frozen?:: Returns whether +self+ is frozen.
-     * - #global_variables:: Returns an array of global variables as symbols.
-     * - #local_variables:: Returns an array of local variables as symbols.
-     * - #test:: Performs specified tests on the given single file or pair of files.
+     * - {#__callee__}[#method-i-__callee__]: Returns the called name
+     *   of the current method as a symbol.
+     * - {#__dir__}[#method-i-__dir__]: Returns the path to the directory
+     *   from which the current method is called.
+     * - {#__method__}[#method-i-__method__]: Returns the name
+     *   of the current method as a symbol.
+     * - #autoload?: Returns the file to be loaded when the given module is referenced.
+     * - #binding: Returns a Binding for the context at the point of call.
+     * - #block_given?: Returns +true+ if a block was passed to the calling method.
+     * - #caller: Returns the current execution stack as an array of strings.
+     * - #caller_locations: Returns the current execution stack as an array
+     *   of Thread::Backtrace::Location objects.
+     * - #class: Returns the class of +self+.
+     * - #frozen?: Returns whether +self+ is frozen.
+     * - #global_variables: Returns an array of global variables as symbols.
+     * - #local_variables: Returns an array of local variables as symbols.
+     * - #test: Performs specified tests on the given single file or pair of files.
      *
      * === Exiting
      *
-     * - #abort:: Exits the current process after printing the given arguments.
-     * - #at_exit:: Executes the given block when the process exits.
-     * - #exit:: Exits the current process after calling any registered
-     *           +at_exit+ handlers.
-     * - #exit!:: Exits the current process without calling any registered
-     *            +at_exit+ handlers.
+     * - #abort: Exits the current process after printing the given arguments.
+     * - #at_exit: Executes the given block when the process exits.
+     * - #exit: Exits the current process after calling any registered
+     *   +at_exit+ handlers.
+     * - #exit!: Exits the current process without calling any registered
+     *   +at_exit+ handlers.
      *
      * === Exceptions
      *
-     * - #catch:: Executes the given block, possibly catching a thrown object.
-     * - #raise (aliased as #fail):: Raises an exception based on the given arguments.
-     * - #throw:: Returns from the active catch block waiting for the given tag.
+     * - #catch: Executes the given block, possibly catching a thrown object.
+     * - #raise (aliased as #fail): Raises an exception based on the given arguments.
+     * - #throw: Returns from the active catch block waiting for the given tag.
      *
      *
      * === \IO
      *
-     * - #gets:: Returns and assigns to <tt>$_</tt> the next line from the current input.
-     * - #open:: Creates an IO object connected to the given stream, file, or subprocess.
-     * - #p::  Prints the given objects' inspect output to the standard output.
-     * - #pp:: Prints the given objects in pretty form.
-     * - #print:: Prints the given objects to standard output without a newline.
-     * - #printf:: Prints the string resulting from applying the given format string
-     *             to any additional arguments.
-     * - #putc:: Equivalent to <tt.$stdout.putc(object)</tt> for the given object.
-     * - #puts:: Equivalent to <tt>$stdout.puts(*objects)</tt> for the given objects.
-     * - #readline:: Similar to #gets, but raises an exception at the end of file.
-     * - #readlines:: Returns an array of the remaining lines from the current input.
-     * - #select:: Same as IO.select.
+     * - ::pp: Prints the given objects in pretty form.
+     * - #gets: Returns and assigns to <tt>$_</tt> the next line from the current input.
+     * - #open: Creates an IO object connected to the given stream, file, or subprocess.
+     * - #p:  Prints the given objects' inspect output to the standard output.
+     * - #print: Prints the given objects to standard output without a newline.
+     * - #printf: Prints the string resulting from applying the given format string
+     *   to any additional arguments.
+     * - #putc: Equivalent to <tt.$stdout.putc(object)</tt> for the given object.
+     * - #puts: Equivalent to <tt>$stdout.puts(*objects)</tt> for the given objects.
+     * - #readline: Similar to #gets, but raises an exception at the end of file.
+     * - #readlines: Returns an array of the remaining lines from the current input.
+     * - #select: Same as IO.select.
      *
      * === Procs
      *
-     * - #lambda:: Returns a lambda proc for the given block.
-     * - #proc:: Returns a new Proc; equivalent to Proc.new.
+     * - #lambda: Returns a lambda proc for the given block.
+     * - #proc: Returns a new Proc; equivalent to Proc.new.
      *
      * === Tracing
      *
-     * - #set_trace_func:: Sets the given proc as the handler for tracing,
-     *                     or disables tracing if given +nil+.
-     * - #trace_var:: Starts tracing assignments to the given global variable.
-     * - #untrace_var:: Disables tracing of assignments to the given global variable.
+     * - #set_trace_func: Sets the given proc as the handler for tracing,
+     *   or disables tracing if given +nil+.
+     * - #trace_var: Starts tracing assignments to the given global variable.
+     * - #untrace_var: Disables tracing of assignments to the given global variable.
      *
      * === Subprocesses
      *
-     * - #`command`:: Returns the standard output of running +command+ in a subshell.
-     * - #exec:: Replaces current process with a new process.
-     * - #fork:: Forks the current process into two processes.
-     * - #spawn:: Executes the given command and returns its pid without waiting
-     *            for completion.
-     * - #system:: Executes the given command in a subshell.
+     * - {`command`}[#method-i-60]: Returns the standard output of running +command+ in a subshell.
+     * - #exec: Replaces current process with a new process.
+     * - #fork: Forks the current process into two processes.
+     * - #spawn: Executes the given command and returns its pid without waiting
+     *   for completion.
+     * - #system: Executes the given command in a subshell.
      *
      * === Loading
      *
-     * - #autoload:: Registers the given file to be loaded when the given constant
-     *               is first referenced.
-     * - #load:: Loads the given Ruby file.
-     * - #require:: Loads the given Ruby file unless it has already been loaded.
-     * - #require_relative:: Loads the Ruby file path relative to the calling file,
-     *                       unless it has already been loaded.
+     * - #autoload: Registers the given file to be loaded when the given constant
+     *   is first referenced.
+     * - #load: Loads the given Ruby file.
+     * - #require: Loads the given Ruby file unless it has already been loaded.
+     * - #require_relative: Loads the Ruby file path relative to the calling file,
+     *   unless it has already been loaded.
      *
      * === Yielding
      *
-     * - #tap:: Yields +self+ to the given block; returns +self+.
-     * - #then (aliased as #yield_self):: Yields +self+ to the block
-     *                                    and returns the result of the block.
+     * - #tap: Yields +self+ to the given block; returns +self+.
+     * - #then (aliased as #yield_self): Yields +self+ to the block
+     *   and returns the result of the block.
      *
      * === \Random Values
      *
-     * - #rand:: Returns a pseudo-random floating point number
-     *           strictly between 0.0 and 1.0.
-     * - #srand:: Seeds the pseudo-random number generator with the given number.
+     * - #rand: Returns a pseudo-random floating point number
+     *   strictly between 0.0 and 1.0.
+     * - #srand: Seeds the pseudo-random number generator with the given number.
      *
      * === Other
      *
-     * - #eval:: Evaluates the given string as Ruby code.
-     * - #loop:: Repeatedly executes the given block.
-     * - #sleep:: Suspends the current thread for the given number of seconds.
-     * - #sprintf (aliased as #format):: Returns the string resulting from applying
-     *                                   the given format string
-     *                                   to any additional arguments.
-     * - #syscall:: Runs an operating system call.
-     * - #trap:: Specifies the handling of system signals.
-     * - #warn:: Issue a warning based on the given messages and options.
+     * - #eval: Evaluates the given string as Ruby code.
+     * - #loop: Repeatedly executes the given block.
+     * - #sleep: Suspends the current thread for the given number of seconds.
+     * - #sprintf (aliased as #format): Returns the string resulting from applying
+     *   the given format string to any additional arguments.
+     * - #syscall: Runs an operating system call.
+     * - #trap: Specifies the handling of system signals.
+     * - #warn: Issue a warning based on the given messages and options.
      *
      */
     rb_mKernel = rb_define_module("Kernel");