What's Here for class Dir (#4472)

What's Here for class Dir

1 files changed, 69 insertions, 0 deletions

diff --git a/dir.c b/dir.c
index b122b2cb90..812cb7cbe4 100644
--- a/dir.c
+++ b/dir.c
@@ -3448,6 +3448,75 @@ rb_dir_s_empty_p(VALUE obj, VALUE dirname)
  *  (<code>config.h</code> and <code>main.rb</code>), the parent
  *  directory (<code>..</code>), and the directory itself
  *  (<code>.</code>).
+ *
+ *  == What's Here
+ *
+ *  \Class \Dir provides methods that are useful for:
+ *
+ *  - {Reading}[#class-Dir-label-Reading]
+ *  - {Setting}[#class-Dir-label-Setting]
+ *  - {Querying}[#class-Dir-label-Querying]
+ *  - {Iterating}[#class-Dir-label-Iterating]
+ *  - {Other}[#class-Dir-label-Other]
+ *
+ *  === Reading
+ *
+ *  - #close:: Closes the directory stream for +self+.
+ *  - #pos=:: Sets the position in the directory stream for +self+.
+ *  - #read:: Reads and returns the next entry in the directory stream for +self+.
+ *  - #rewind:: Sets the position in the directory stream for +self+ to the first entry.
+ *  - #seek:: Sets the position in the directory stream for +self+
+ *            the entry at the given offset.
+ *
+ *  === Setting
+ *
+ *  - ::chdir:: Changes the working directory of the current process
+ *              to the given directory.
+ *  - ::chroot:: Changes the file-system root for the current process
+ *               to the given directory.
+ *
+ *  === Querying
+ *
+ *  - ::[]:: Same as ::glob without the ability to pass flags.
+ *  - ::children:: Returns an array of names of the children
+ *                 (both files and directories) of the given directory,
+ *                 but not including <tt>.</tt> or <tt>..</tt>.
+ *  - ::empty?:: Returns whether the given path is an empty directory.
+ *  - ::entries:: Returns an array of names of the children
+ *                (both files and directories) of the given directory,
+ *                including <tt>.</tt> and <tt>..</tt>.
+ *  - ::exist?:: Returns whether the given path is a directory.
+ *  - ::getwd (aliased as #pwd):: Returns the path to the current working directory.
+ *  - ::glob:: Returns an array of file paths matching the given pattern and flags.
+ *  - ::home:: Returns the home directory path for a given user or the current user.
+ *  - #children:: Returns an array of names of the children
+ *                (both files and directories) of +self+,
+ *                but not including <tt>.</tt> or <tt>..</tt>.
+ *  - #fileno:: Returns the integer file descriptor for +self+.
+ *  - #path (aliased as #to_path):: Returns the path used to create +self+.
+ *  - #tell (aliased as #pos):: Returns the integer position
+ *                              in the directory stream for +self+.
+ *
+ *  === Iterating
+ *
+ *  - ::each_child:: Calls the given block with each entry in the given directory,
+ *                   but not including <tt>.</tt> or <tt>..</tt>.
+ *  - ::foreach:: Calls the given block with each entryin the given directory,
+ *                including <tt>.</tt> and <tt>..</tt>.
+ *  - #each:: Calls the given block with each entry in +self+,
+ *            including <tt>.</tt> and <tt>..</tt>.
+ *  - #each_child:: Calls the given block with each entry in +self+,
+ *                  but not including <tt>.</tt> or <tt>..</tt>.
+ *
+ *  === Other
+ *
+ *  - ::mkdir:: Creates a directory at the given path, with optional permissions.
+ *  - ::new:: Returns a new \Dir for the given path, with optional encoding.
+ *  - ::open:: Same as ::new, but if a block is given, yields the \Dir to the block,
+ *             closing it upon block exit.
+ *  - ::unlink (aliased as ::delete and ::rmdir):: Removes the given directory.
+ *  - #inspect:: Returns a string description of +self+.
+ *
  */
 void
 Init_Dir(void)