[DOC] Harmonize sticky? methods (#18987)

Merged-By: peterzhu2118 <peter@peterzhu.ca>

file.c

@@ -2581,12 +2581,29 @@ rb_file_sgid_p(VALUE obj, VALUE fname)
 }
 
 /*
+ * :markup: markdown
+
  * call-seq:
- *   File.sticky?(file_name)   ->  true or false
+ *   File.sticky?(object) -> true or false
  *
- * Returns +true+ if the named file has the sticky bit set.
+ * Returns whether the sticky bit is set
+ * in the [special bits](rdoc-ref:file/filesystem_modes.md@Special+Bits)
+ * for the given `object`, which may be a path or an IO object:
  *
- * _file_name_ can be an IO object.
+ * ```ruby
+ * filepath = '/tmp/t.tmp'
+ * File.write(filepath, 'foo')
+ * mode = File.stat(filepath).mode.to_s(8) # => "100664"
+ * File.sticky?(filepath)                  # => false
+ * File.chmod(01644, filepath)             # Set sticky bit.
+ * mode = File.stat(filepath).mode.to_s(8) # => "101644"
+ * File.sticky?(filepath)                  # => true
+ * File.delete(filepath)                   # Clean up.
+ * File.sticky?($stdin)                    # => false
+ * File.sticky?('nosuch')                  # => false
+ * ```
+ *
+ * Returns `false` on Windows.
  */
 
 static VALUE
@@ -7366,14 +7383,31 @@ rb_stat_sgid(VALUE obj)
 }
 
 /*
+ *  :markup: markdown
+
  *  call-seq:
- *     stat.sticky?    -> true or false
+ *    sticky? -> true or false
  *
- *  Returns +true+ if <i>stat</i> has its sticky bit set, +false+ if it
- *  doesn't or if the operating system doesn't support this feature.
+ * Returns whether the sticky bit is set
+ * in the [special bits](rdoc-ref:file/filesystem_modes.md@Special+Bits)
+ * for `self`:
  *
- *     File.stat("testfile").sticky?   #=> false
+ * ```ruby
+ * filepath = '/tmp/t.tmp'
+ * File.write(filepath, 'foo')
+ * stat = File.stat(filepath)
+ * stat.sticky?                # => false
+ * stat.mode.to_s(8)           # => "100664"
+ * File.chmod(01644, filepath) # => 1        # Stat unchanged.
+ * stat.sticky?                # => false
+ * stat.mode.to_s(8)           # => "100664"
+ * stat = File.stat(filepath)                # Fresh stat.
+ * stat.sticky?                # => true
+ * stat.mode.to_s(8)           # => "101644"
+ * File.delete(filepath)                     # Clean up.
+ * ```
  *
+ * Returns `false` on Windows.
  */
 
 static VALUE

pathname_builtin.rb

@@ -2686,18 +2686,19 @@ class Pathname    # * FileTest *
   # call-seq:
   #   sticky? -> true or false
   #
-  # Returns whether the [sticky bit](https://en.wikipedia.org/wiki/Sticky_bit) is set
+  # Returns whether the sticky bit is set
+  # in the [special bits](rdoc-ref:file/filesystem_modes.md@Special+Bits)
   # for the entry at the path in `self`:
   #
   # ```ruby
-  # pn = Pathname('t.tmp')
+  # pn = Pathname('/tmp/t.tmp')
   # pn.write('foo')
   # pn.stat.mode.to_s(8) # => "100664"
   # pn.sticky?           # => false
-  # pn.chmod(0o1644)
-  # pn.stat.mode.to_s(8) # => "101644"
+  # pn.chmod(01644)      # Set sticky bit.
+  # pn.stat.mode.to_s(8) #  => "101644"
   # pn.sticky?           # => true
-  # pn.delete
+  # pn.delete # => 1     # Clean up.
   # ```
   #
   # Returns `false` on Windows.