From 688a1314e60b0e58d5325f50c02552e3018c5025 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Sat, 23 Dec 2023 15:08:26 -0600
Subject: [PATCH] [DOC] Clean up doc for File#flock (#9332)

---
 file.c | 94 +++++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 61 insertions(+), 33 deletions(-)

diff --git a/file.c b/file.c
index fd1fbf2d97..fee3840452 100644
--- a/file.c
+++ b/file.c
@@ -5222,47 +5222,75 @@ rb_thread_flock(void *data)
     return (VALUE)ret;
 }
 
-/*
+/*  :markup: markdown
+ *
  *  call-seq:
- *     file.flock(locking_constant) -> 0 or false
+ *    flock(locking_constant) -> 0 or false
  *
- *  Locks or unlocks a file according to <i>locking_constant</i> (a
- *  logical <em>or</em> of the values in the table below).
- *  Returns <code>false</code> if File::LOCK_NB is specified and the
- *  operation would otherwise have blocked. Not available on all
- *  platforms.
+ *  Locks or unlocks a file according to the given `locking_constant`,
+ *  a bitwise OR of the values in the table below.
  *
- *  Locking constants (in class File):
+ *  Not available on all platforms.
  *
- *     LOCK_EX   | Exclusive lock. Only one process may hold an
- *               | exclusive lock for a given file at a time.
- *     ----------+------------------------------------------------
- *     LOCK_NB   | Don't block when locking. May be combined
- *               | with other lock options using logical or.
- *     ----------+------------------------------------------------
- *     LOCK_SH   | Shared lock. Multiple processes may each hold a
- *               | shared lock for a given file at the same time.
- *     ----------+------------------------------------------------
- *     LOCK_UN   | Unlock.
+ *  Returns `false` if `File::LOCK_NB` is specified and the operation would have blocked;
+ *  otherwise returns `0`.
+ *  <br>
  *
+ *  <table>
+ *    <tr>
+ *      <th colspan="3">Locking Constants</th>
+ *    </tr>
+ *    <tr>
+ *      <th>Constant</th>
+ *      <th>Lock</th>
+ *      <th>Effect</th>
+ *    </tr>
+ *    <tr>
+ *    <td><tt>File::LOCK_EX</tt></td>
+ *    <td>Exclusive</td>
+ *      <td>Only one process may hold an exclusive lock for <tt>self</tt> at a time.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><tt>File::LOCK_NB</tt></td>
+ *      <td>Non-blocking</td>
+ *      <td>
+ *        No blocking; may be combined with other `File::LOCK_SH` or `File::LOCK_EX`
+ *        using the bitwise OR operator <tt>|</tt>.
+ *      </td>
+ *    </tr>
+ *    <tr>
+ *      <td><tt>File::LOCK_SH</tt></td>
+ *      <td>Shared</td>
+ *      <td>Multiple processes may each hold a shared lock for <tt>self</tt> at the same time.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><tt>File::LOCK_UN</tt></td>
+ *      <td>Unlock</td>
+ *      <td>Remove an existing lock held by this process.</td>
+ *    </tr>
+ *  </table>
+ *
+ *  <br>
  *  Example:
  *
- *     # update a counter using write lock
- *     # don't use "w" because it truncates the file before lock.
- *     File.open("counter", File::RDWR|File::CREAT, 0644) {|f|
- *       f.flock(File::LOCK_EX)
- *       value = f.read.to_i + 1
- *       f.rewind
- *       f.write("#{value}\n")
- *       f.flush
- *       f.truncate(f.pos)
- *     }
+ *  ```ruby
+ *  # Update a counter using an exclusive lock.
+ *  # Don't use File::WRONLY because it truncates the file.
+ *  File.open('counter', File::RDWR | File::CREAT, 0644) do |f|
+ *    f.flock(File::LOCK_EX)
+ *    value = f.read.to_i + 1
+ *    f.rewind
+ *    f.write("#{value}\n")
+ *    f.flush
+ *    f.truncate(f.pos)
+ *  end
  *
- *     # read the counter using read lock
- *     File.open("counter", "r") {|f|
- *       f.flock(File::LOCK_SH)
- *       p f.read
- *     }
+ *  # Read the counter using a shared lock.
+ *  File.open('counter', 'r') do |f|
+ *    f.flock(File::LOCK_SH)
+ *    f.read
+ *  end
+ *  ```
  *
  */