rbs 3.0.0.dev.2 → 3.0.0.dev.3

data/stdlib/etc/0/etc.rbs

@@ -1,10 +1,10 @@
 # <!-- rdoc-file=ext/etc/etc.c -->
 # The Etc module provides access to information typically stored in files in the
-# /etc directory on Unix systems.
+# `/etc` directory on Unix systems.
 #
 # The information accessible consists of the information found in the
-# /etc/passwd and /etc/group files, plus information about the system's
-# temporary directory (/tmp) and configuration directory (/etc).
+# `/etc/passwd` and `/etc/group` files, plus information about the system's
+# temporary directory (`/tmp`) and configuration directory (`/etc`).
 #
 # The Etc module provides a more reliable way to access information about the
 # logged in user than environment variables such as +$USER+.
@@ -48,8 +48,8 @@ module Etc
   #   rdoc-file=ext/etc/etc.c
   #   - endgrent()
   # -->
-  # Ends the process of scanning through the /etc/group file begun by ::getgrent,
-  # and closes the file.
+  # Ends the process of scanning through the `/etc/group` file begun by
+  # ::getgrent, and closes the file.
   #
   def self?.endgrent: () -> void
 
@@ -57,7 +57,7 @@ module Etc
   #   rdoc-file=ext/etc/etc.c
   #   - endpwent()
   # -->
-  # Ends the process of scanning through the /etc/passwd file begun with
+  # Ends the process of scanning through the `/etc/passwd` file begun with
   # ::getpwent, and closes the file.
   #
   def self?.endpwent: () -> void
@@ -66,7 +66,7 @@ module Etc
   #   rdoc-file=ext/etc/etc.c
   #   - getgrent()
   # -->
-  # Returns an entry from the /etc/group file.
+  # Returns an entry from the `/etc/group` file.
   #
   # The first time it is called it opens the file and returns the first entry;
   # each successive call returns the next entry, or `nil` if the end of the file
@@ -83,7 +83,7 @@ module Etc
   #   - getgrgid(group_id)  ->       Group
   # -->
   # Returns information about the group with specified integer `group_id`, as
-  # found in /etc/group.
+  # found in `/etc/group`.
   #
   # The information is returned as a Group struct.
   #
@@ -101,7 +101,7 @@ module Etc
   #   - getgrnam(name)       ->  Group
   # -->
   # Returns information about the group with specified `name`, as found in
-  # /etc/group.
+  # `/etc/group`.
   #
   # The information is returned as a Group struct.
   #
@@ -136,7 +136,7 @@ module Etc
   #   rdoc-file=ext/etc/etc.c
   #   - getpwent()
   # -->
-  # Returns an entry from the /etc/passwd file.
+  # Returns an entry from the `/etc/passwd` file.
   #
   # The first time it is called it opens the file and returns the first entry;
   # each successive call returns the next entry, or `nil` if the end of the file
@@ -152,7 +152,8 @@ module Etc
   #   rdoc-file=ext/etc/etc.c
   #   - getpwnam(name)       ->  Passwd
   # -->
-  # Returns the /etc/passwd information for the user with specified login `name`.
+  # Returns the `/etc/passwd` information for the user with specified login
+  # `name`.
   #
   # The information is returned as a Passwd struct.
   #
@@ -169,7 +170,8 @@ module Etc
   #   rdoc-file=ext/etc/etc.c
   #   - getpwuid(uid)        ->  Passwd
   # -->
-  # Returns the /etc/passwd information for the user with the given integer `uid`.
+  # Returns the `/etc/passwd` information for the user with the given integer
+  # `uid`.
   #
   # The information is returned as a Passwd struct.
   #
@@ -189,7 +191,7 @@ module Etc
   #   - group()
   # -->
   # Provides a convenient Ruby iterator which executes a block for each entry in
-  # the /etc/group file.
+  # the `/etc/group` file.
   #
   # The code block is passed an Group struct.
   #
@@ -242,7 +244,7 @@ module Etc
   #   - Etc.passwd                   ->  Passwd
   # -->
   # Provides a convenient Ruby iterator which executes a block for each entry in
-  # the /etc/passwd file.
+  # the `/etc/passwd` file.
   #
   # The code block is passed an Passwd struct.
   #
@@ -263,7 +265,7 @@ module Etc
   #   rdoc-file=ext/etc/etc.c
   #   - setgrent()
   # -->
-  # Resets the process of reading the /etc/group file, so that the next call to
+  # Resets the process of reading the `/etc/group` file, so that the next call to
   # ::getgrent will return the first entry again.
   #
   def self?.setgrent: () -> void
@@ -272,7 +274,7 @@ module Etc
   #   rdoc-file=ext/etc/etc.c
   #   - setpwent()
   # -->
-  # Resets the process of reading the /etc/passwd file, so that the next call to
+  # Resets the process of reading the `/etc/passwd` file, so that the next call to
   # ::getpwent will return the first entry again.
   #
   def self?.setpwent: () -> void
@@ -299,10 +301,11 @@ module Etc
   # -->
   # Returns system configuration directory.
   #
-  # This is typically "/etc", but is modified by the prefix used when Ruby was
-  # compiled. For example, if Ruby is built and installed in /usr/local, returns
-  # "/usr/local/etc" on other platforms than Windows. On Windows, this always
-  # returns the directory provided by the system.
+  # This is typically `"/etc"`, but is modified by the prefix used when Ruby was
+  # compiled. For example, if Ruby is built and installed in `/usr/local`, returns
+  # `"/usr/local/etc"` on other platforms than Windows.
+  #
+  # On Windows, this always returns the directory provided by the system.
   #
   def self?.sysconfdir: () -> ::String
 
@@ -651,11 +654,51 @@ module Etc
 
   VERSION: String
 
+  # <!-- rdoc-file=ext/etc/etc.c -->
+  # Group is a placeholder Struct for user group database on Unix systems.
+  #
+  # ### The struct contains the following members
+  #
+  # name
+  # :   contains the name of the group as a String.
+  # passwd
+  # :   contains the encrypted password as a String. An `'x'` is returned if
+  #     password access to the group is not available; an empty string is returned
+  #     if no password is needed to obtain membership of the group. This is
+  #     system-dependent.
+  # gid
+  # :   contains the group's numeric ID as an integer.
+  # mem
+  # :   is an Array of Strings containing the short login names of the members of
+  #     the group.
+  #
   class Group < Struct[untyped]
     extend Enumerable[untyped]
 
     def self.[]: (*untyped) -> untyped
 
+    # <!--
+    #   rdoc-file=ext/etc/etc.c
+    #   - Etc::Group.each { |group| block }   ->       obj
+    #   - Etc::Group.each                          ->     Enumerator
+    # -->
+    # Iterates for each entry in the `/etc/group` file if a block is given.
+    #
+    # If no block is given, returns the Enumerator.
+    #
+    # The code block is passed a Group struct.
+    #
+    # Example:
+    #
+    #     require 'etc'
+    #
+    #     Etc::Group.each {|g|
+    #       puts g.name + ": " + g.mem.join(', ')
+    #     }
+    #
+    #     Etc::Group.collect {|g| g.name}
+    #     Etc::Group.select {|g| !g.mem.empty?}
+    #
     def self.each: () -> untyped
 
     def self.inspect: () -> untyped
@@ -685,11 +728,75 @@ module Etc
     def passwd=: (String new_passwd) -> void
   end
 
+  # <!-- rdoc-file=ext/etc/etc.c -->
+  # Passwd is a placeholder Struct for user database on Unix systems.
+  #
+  # ### The struct contains the following members
+  #
+  # name
+  # :   contains the short login name of the user as a String.
+  # passwd
+  # :   contains the encrypted password of the user as a String. an `'x'` is
+  #     returned if shadow passwords are in use. An `'*'` is returned if the user
+  #     cannot log in using a password.
+  # uid
+  # :   contains the integer user ID (uid) of the user.
+  # gid
+  # :   contains the integer group ID (gid) of the user's primary group.
+  # dir
+  # :   contains the path to the home directory of the user as a String.
+  # shell
+  # :   contains the path to the login shell of the user as a String.
+  #
+  #
+  # ### The following members below are system-dependent
+  #
+  # gecos
+  # :   contains a longer String description of the user, such as a full name.
+  #     Some Unix systems provide structured information in the gecos field, but
+  #     this is system-dependent.
+  # change
+  # :   password change time(integer).
+  # quota
+  # :   quota value(integer).
+  # age
+  # :   password age(integer).
+  # class
+  # :   user access class(string).
+  # comment
+  # :   comment(string).
+  # expire
+  # :   account expiration time(integer).
+  #
   class Passwd < Struct[untyped]
     extend Enumerable[untyped]
 
     def self.[]: (*untyped) -> untyped
 
+    # <!--
+    #   rdoc-file=ext/etc/etc.c
+    #   - Etc::Passwd.each { |struct| block }  ->  Passwd
+    #   - Etc::Passwd.each                     ->  Enumerator
+    # -->
+    # Iterates for each entry in the `/etc/passwd` file if a block is given.
+    #
+    # If no block is given, returns the Enumerator.
+    #
+    # The code block is passed an Passwd struct.
+    #
+    # See Etc.getpwent above for details.
+    #
+    # Example:
+    #
+    #     require 'etc'
+    #
+    #     Etc::Passwd.each {|u|
+    #       puts u.name + " = " + u.gecos
+    #     }
+    #
+    #     Etc::Passwd.collect {|u| u.gecos}
+    #     Etc::Passwd.collect {|u| u.gecos}
+    #
     def self.each: () -> untyped
 
     def self.inspect: () -> untyped