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 locking_constant (a
- * logical or of the values in the table below).
- * Returns false
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`.
+ *
*
+ *
Locking Constants | + *||
---|---|---|
Constant | + *Lock | + *Effect | + *
File::LOCK_EX | + *Exclusive | + *Only one process may hold an exclusive lock for self at a time. | + *
File::LOCK_NB | + *Non-blocking | + *+ * No blocking; may be combined with other `File::LOCK_SH` or `File::LOCK_EX` + * using the bitwise OR operator |. + * | + *
File::LOCK_SH | + *Shared | + *Multiple processes may each hold a shared lock for self at the same time. | + *
File::LOCK_UN | + *Unlock | + *Remove an existing lock held by this process. | + *