* ext/dl/win32/lib/win32/registry.rb: update rdoc. [ruby-core:26022]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@25626 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 242 insertions, 236 deletions

diff --git a/ext/dl/win32/lib/win32/registry.rb b/ext/dl/win32/lib/win32/registry.rb
index a2b69a08fe..5742d0f376 100644
--- a/ext/dl/win32/lib/win32/registry.rb
+++ b/ext/dl/win32/lib/win32/registry.rb
@@ -1,5 +1,9 @@
-=begin
-= Win32 Registry I/F
+require 'dl/import'
+module Win32
+
+=begin rdoc
+= Win32 Registry
+
 win32/registry is registry accessor library for Win32 platform.
 It uses dl/import to call Win32 Registry APIs.
 
@@ -24,247 +28,69 @@ It uses dl/import to call Win32 Registry APIs.
 
 == Win32::Registry class
 
-=== including modules
-
-* Enumerable
-* Registry::Constants
-
-=== class methods
---- Registry.open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)
---- Registry.open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) { |reg| ... }
-    Open the registry key ((|subkey|)) under ((|key|)).
-    ((|key|)) is Win32::Registry object of parent key.
-    You can use predefined key HKEY_* (see ((<constants>)))
-
-    ((|desired|)) and ((|opt|)) is access mask and key option.
-    For detail, see ((<MSDN Library|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/regopenkeyex.asp>)).
-
-    If block is given, the key is closed automatically.
-
---- Registry.create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)
---- Registry.create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) { |reg| ... }
-    Create or open the registry key ((|subkey|)) under ((|key|)).
-    You can use predefined key HKEY_* (see ((<constants>)))
-
-    If subkey is already exists, key is opened and Registry#((<created?>))
-    method will return false.
-
-    If block is given, the key is closed automatically.
-
---- Registry.expand_environ(str)
-    Replace (({%\w+%})) into the environment value of ((|str|)).
-    This method is used for REG_EXPAND_SZ.
-
-    For detail, see ((<ExpandEnvironmentStrings|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/expandenvironmentstrings.asp>)) Win32 API.
-
---- Registry.type2name(type)
-    Convert registry type value to readable string.
-
---- Registry.wtime2time(wtime)
-    Convert 64-bit FILETIME integer into Time object.
-
---- Registry.time2wtime(time)
-    Convert Time object or Integer object into 64-bit FILETIME.
-
-=== instance methods
---- open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)
-    Same as (({Win32::((<Registry.open>))(self, subkey, desired, opt)}))
-
---- create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)
-    Same as (({Win32::((<Registry.create>))(self, subkey, desired, opt)}))
-
---- close
-    Close key.
-
-    After closed, most method raises error.
-
---- read(name, *rtype)
-    Read a registry value named ((|name|)) and return array of
-    [ ((|type|)), ((|data|)) ].
-    When name is nil, the `default' value is read.
-
-    ((|type|)) is value type. (see ((<Win32::Registry::Constants module>)))
-    ((|data|)) is value data, its class is:
-    :REG_SZ, REG_EXPAND_SZ
-       String
-    :REG_MULTI_SZ
-       Array of String
-    :REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_QWORD
-       Integer
-    :REG_BINARY
-       String (contains binary data)
-
-    When ((|rtype|)) is specified, the value type must be included by
-    ((|rtype|)) array, or TypeError is raised.
-
---- self[name, *rtype]
-    Read a registry value named ((|name|)) and return its value data.
-    The class of value is same as ((<read>)) method returns.
-
-    If the value type is REG_EXPAND_SZ, returns value data whose environment
-    variables are replaced.
-    If the value type is neither REG_SZ, REG_MULTI_SZ, REG_DWORD,
-    REG_DWORD_BIG_ENDIAN, nor REG_QWORD, TypeError is raised.
-
-    The meaning of ((|rtype|)) is same as ((<read>)) method.
-
---- read_s(name)
---- read_i(name)
---- read_bin(name)
-    Read a REG_SZ(read_s), REG_DWORD(read_i), or REG_BINARY(read_bin)
-    registry value named ((|name|)).
-
-    If the values type does not match, TypeError is raised.
-
---- read_s_expand(name)
-    Read a REG_SZ or REG_EXPAND_SZ registry value named ((|name|)).
-
-    If the value type is REG_EXPAND_SZ, environment variables are replaced.
-    Unless the value type is REG_SZ or REG_EXPAND_SZ, TypeError is raised.
-
---- write(name, type, data)
-    Write ((|data|)) to a registry value named ((|name|)).
-    When name is nil, write to the `default' value.
-
-    ((|type|)) is type value. (see ((<Registry::Constants module>)))
-    Class of ((|data|)) must be same as which ((<read>))
-    method returns.
-
---- self[name, wtype = nil] = value
-    Write ((|value|)) to a registry value named ((|name|)).
-
-    If ((|wtype|)) is specified, the value type is it.
-    Otherwise, the value type is depend on class of ((|value|)):
-    :Integer
-      REG_DWORD
-    :String
-      REG_SZ
-    :Array
-      REG_MULTI_SZ
-
---- write_s(name, value)
---- write_i(name, value)
---- write_bin(name, value)
-    Write ((|value|)) to a registry value named ((|name|)).
-
-    The value type is REG_SZ(write_s), REG_DWORD(write_i), or
-    REG_BINARY(write_bin).
-
---- each { |name, type, value| ... }
---- each_value { |name, type, value| ... }
-    Enumerate values.
-
---- each_key { |subkey, wtime| ... }
-    Enumerate subkeys.
-
-    ((|subkey|)) is String which contains name of subkey.
-    ((|wtime|)) is last write time as FILETIME (64-bit integer).
-    (see ((<Registry.wtime2time>)))
-
---- delete(name)
---- delete_value(name)
-    Delete a registry value named ((|name|)).
-    We can not delete the `default' value.
-
---- delete_key(name, recursive = false)
-    Delete a subkey named ((|name|)) and all its values.
-
-    If ((|recursive|)) is false, the subkey must not have subkeys.
-    Otherwise, this method deletes all subkeys and values recursively.
-
---- flush
-    Write all the attributes into the registry file.
-
---- created?
-    Returns if key is created ((*newly*)).
-    (see ((<Registry.create>)))
-
---- open?
-    Returns if key is not closed.
-
---- hkey
-    Returns key handle value.
-
---- parent
-    Win32::Registry object of parent key, or nil if predefeined key.
-
---- keyname
-    Same as ((|subkey|)) value of ((<Registry.open>)) or
-    ((<Registry.create>)) method.
-
---- disposition
-    Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY).
-
---- name
---- to_s
-    Full path of key such as (({'HKEY_CURRENT_USER\SOFTWARE\foo\bar'})).
-
 --- info
-    Returns key information as Array of:
-    :num_keys
-      The number of subkeys.
-    :max_key_length
-      Maximum length of name of subkeys.
-    :num_values
-      The number of values.
-    :max_value_name_length
-      Maximum length of name of values.
-    :max_value_length
-      Maximum length of value of values.
-    :descriptor_length
-      Length of security descriptor.
-    :wtime
-      Last write time as FILETIME(64-bit integer)
-
-    For detail, see ((<RegQueryInfoKey|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/regqueryinfokey.asp>)) Win32 API.
 
 --- num_keys
+
 --- max_key_length
+
 --- num_values
+
 --- max_value_name_length
+
 --- max_value_length
+
 --- descriptor_length
+
 --- wtime
     Returns an item of key information.
 
 === constants
 --- HKEY_CLASSES_ROOT
---- HKEY_CURRENT_USER
---- HKEY_LOCAL_MACHINE
---- HKEY_PERFORMANCE_DATA
---- HKEY_CURRENT_CONFIG
---- HKEY_DYN_DATA
-    Win32::Registry object whose key is predefined key.
-    For detail, see ((<MSDN Library|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/predefined_keys.asp>)).
 
-== Win32::Registry::Constants module
-
-For detail, see ((<MSDN Library|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/registry.asp>)).
-
---- HKEY_*
-    Predefined key ((*handle*)).
-    These are Integer, not Win32::Registry.
+--- HKEY_CURRENT_USER
 
---- REG_*
-    Registry value type.
+--- HKEY_LOCAL_MACHINE
 
---- KEY_*
-    Security access mask.
+--- HKEY_PERFORMANCE_DATA
 
---- KEY_OPTIONS_*
-    Key options.
+--- HKEY_CURRENT_CONFIG
 
---- REG_CREATED_NEW_KEY
---- REG_OPENED_EXISTING_KEY
-    If the key is created newly or opened existing key.
-    See also Registry#((<disposition>)) method.
+--- HKEY_DYN_DATA
 
-=end
+    Win32::Registry object whose key is predefined key.
+For detail, see the MSDN[http://msdn.microsoft.com/library/en-us/sysinfo/base/predefined_keys.asp] article.
 
-require 'dl/import'
+=end rdoc
 
-module Win32
   class Registry
+
+    #
+    # For detail, see the MSDN[http://msdn.microsoft.com/library/en-us/sysinfo/base/registry.asp].
+    #
+    # --- HKEY_*
+    #
+    #     Predefined key ((*handle*)).
+    #     These are Integer, not Win32::Registry.
+    #
+    # --- REG_*
+    #
+    #     Registry value type.
+    #
+    # --- KEY_*
+    #
+    #     Security access mask.
+    #
+    # --- KEY_OPTIONS_*
+    #
+    #     Key options.
+    #
+    # --- REG_CREATED_NEW_KEY
+    #
+    # --- REG_OPENED_EXISTING_KEY
+    #
+    #     If the key is created newly or opened existing key.
+    #     See also Registry#disposition method.
     module Constants
       HKEY_CLASSES_ROOT = 0x80000000
       HKEY_CURRENT_USER = 0x80000001
@@ -365,7 +191,7 @@ module Win32
         raise Error.new(5) ## ERROR_ACCESS_DENIED
       end
 
-      # Fake class for Registry#open, Registry#create
+      # Fake #class method for Registry#open, Registry#create
       def class
         Registry
       end
@@ -498,7 +324,10 @@ module Win32
     end
 
     #
-    # utility functions
+    # Replace %\w+% into the environment value of what is contained between the %'s
+    # This method is used for REG_EXPAND_SZ.
+    #
+    # For detail, see expandEnvironmentStrings[http://msdn.microsoft.com/library/en-us/sysinfo/base/expandenvironmentstrings.asp] \Win32 \API.
     #
     def self.expand_environ(str)
       str.gsub(/%([^%]+)%/) { ENV[$1] || ENV[$1.upcase] || $& }
@@ -514,23 +343,43 @@ module Win32
       @@type2name[Constants.const_get(type)] = type
     end
 
+    #
+    # Convert registry type value to readable string.
+    #
     def self.type2name(type)
       @@type2name[type] || type.to_s
     end
 
+    #
+    # Convert 64-bit FILETIME integer into Time object.
+    #
     def self.wtime2time(wtime)
       Time.at((wtime - 116444736000000000) / 10000000)
     end
 
+    #
+    # Convert Time object or Integer object into 64-bit FILETIME.
+    #
     def self.time2wtime(time)
       time.to_i * 10000000 + 116444736000000000
     end
 
     #
-    # constructors
+    # constructor
     #
     private_class_method :new
 
+    #
+    # --- Registry.open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)
+    #
+    # --- Registry.open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) { |reg| ... }
+    #
+    # Open the registry key subkey under key.
+    # key is Win32::Registry object of parent key.
+    # You can use predefined key HKEY_* (see Constants)
+    # desired and opt is access mask and key option.
+    # For detail, see the MSDN[http://msdn.microsoft.com/library/en-us/sysinfo/base/regopenkeyex.asp].
+    # If block is given, the key is closed automatically.
     def self.open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)
       subkey = subkey.chomp('\\')
       newkey = API.OpenKey(hkey.hkey, subkey, opt, desired)
@@ -546,6 +395,19 @@ module Win32
       end
     end
 
+    #
+    # --- Registry.create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)
+    #
+    # --- Registry.create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) { |reg| ... }
+    #
+    # Create or open the registry key subkey under key.
+    # You can use predefined key HKEY_* (see Constants)
+    #
+    # If subkey is already exists, key is opened and Registry#created?
+    # method will return false.
+    #
+    # If block is given, the key is closed automatically.
+    #
     def self.create(hkey, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)
       newkey, disp = API.CreateKey(hkey.hkey, subkey, opt, desired)
       obj = new(newkey, hkey, subkey, disp)
@@ -576,19 +438,37 @@ module Win32
       @hkeyfinal = [ hkey ]
       ObjectSpace.define_finalizer self, @@final.call(@hkeyfinal)
     end
-    attr_reader :hkey, :parent, :keyname, :disposition
+
+    #  Returns key handle value.
+    attr_reader :hkey
+    # Win32::Registry object of parent key, or nil if predefeined key.
+    attr_reader :parent
+    # Same as subkey value of Registry.open or
+    # Registry.create method.
+    attr_reader :keyname
+    #  Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY).
+    attr_reader :disposition
 
     #
-    # attributes
+    # Returns if key is created ((*newly*)).
+    # (see Registry.create) -- basically you call create
+    # then when you call created? on the instance returned
+    # it will tell if it was successful or not
     #
     def created?
       @disposition == REG_CREATED_NEW_KEY
     end
 
+    #
+    # Returns if key is not closed.
+    #
     def open?
       !@hkey.nil?
     end
 
+    #
+    # Full path of key such as 'HKEY_CURRENT_USER\SOFTWARE\foo\bar'.
+    #
     def name
       parent = self
       name = @keyname
@@ -603,23 +483,31 @@ module Win32
     end
 
     #
-    # marshalling
+    # marshalling is not allowed
     #
     def _dump(depth)
       raise TypeError, "can't dump Win32::Registry"
     end
 
     #
-    # open/close
+    # Same as Win32::Registry.open (self, subkey, desired, opt)
     #
     def open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED, &blk)
       self.class.open(self, subkey, desired, opt, &blk)
     end
 
+    #
+    # Same as Win32::Registry.create (self, subkey, desired, opt)
+    #
     def create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED, &blk)
       self.class.create(self, subkey, desired, opt, &blk)
     end
 
+    #
+    # Close key.
+    #
+    # After close, most method raise an error.
+    #
     def close
       API.CloseKey(@hkey)
       @hkey = @parent = @keyname = nil
@@ -627,7 +515,7 @@ module Win32
     end
 
     #
-    # iterator
+    # Enumerate values.
     #
     def each_value
       index = 0
@@ -649,6 +537,13 @@ module Win32
     end
     alias each each_value
 
+    #
+    # Enumerate subkeys.
+    #
+    # subkey is String which contains name of subkey.
+    # wtime is last write time as FILETIME (64-bit integer).
+    # (see Registry.wtime2time)
+    #
     def each_key
       index = 0
       while true
@@ -663,15 +558,31 @@ module Win32
       index
     end
 
+    #
+    # return keys as an array
+    #
     def keys
       keys_ary = []
       each_key { |key,| keys_ary << key }
       keys_ary
     end
 
-    #
-    # reader
-    #
+    # Read a registry value named name and return array of
+    # [ type, data ].
+    # When name is nil, the `default' value is read.
+    # type is value type. (see Win32::Registry::Constants module)
+    # data is value data, its class is:
+    # :REG_SZ, REG_EXPAND_SZ
+    #    String
+    # :REG_MULTI_SZ
+    #    Array of String
+    # :REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_QWORD
+    #    Integer
+    # :REG_BINARY
+    #    String (contains binary data)
+    #
+    # When rtype is specified, the value type must be included by
+    # rtype array, or TypeError is raised.
     def read(name, *rtype)
       type, data = API.QueryValue(@hkey, name)
       unless rtype.empty? or rtype.include?(type)
@@ -695,6 +606,17 @@ module Win32
       end
     end
 
+    #
+    # Read a registry value named name and return its value data.
+    # The class of value is same as #read method returns.
+    #
+    # If the value type is REG_EXPAND_SZ, returns value data whose environment
+    # variables are replaced.
+    # If the value type is neither REG_SZ, REG_MULTI_SZ, REG_DWORD,
+    # REG_DWORD_BIG_ENDIAN, nor REG_QWORD, TypeError is raised.
+    #
+    # The meaning of rtype is same as #read method.
+    #
     def [](name, *rtype)
       type, data = read(name, *rtype)
       case type
@@ -707,10 +629,20 @@ module Win32
       end
     end
 
+    # Read a REG_SZ(read_s), REG_DWORD(read_i), or REG_BINARY(read_bin)
+    # registry value named name.
+    #
+    # If the values type does not match, TypeError is raised.
     def read_s(name)
       read(name, REG_SZ)[1]
     end
 
+    #
+    # Read a REG_SZ or REG_EXPAND_SZ registry value named name.
+    #
+    # If the value type is REG_EXPAND_SZ, environment variables are replaced.
+    # Unless the value type is REG_SZ or REG_EXPAND_SZ, TypeError is raised.
+    #
     def read_s_expand(name)
       type, data = read(name, REG_SZ, REG_EXPAND_SZ)
       if type == REG_EXPAND_SZ
@@ -720,16 +652,33 @@ module Win32
       end
     end
 
+    #
+    # Read a REG_SZ(read_s), REG_DWORD(read_i), or REG_BINARY(read_bin)
+    # registry value named name.
+    #
+    # If the values type does not match, TypeError is raised.
+    #
     def read_i(name)
       read(name, REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_QWORD)[1]
     end
 
+    #
+    # Read a REG_SZ(read_s), REG_DWORD(read_i), or REG_BINARY(read_bin)
+    # registry value named name.
+    #
+    # If the values type does not match, TypeError is raised.
+    #
     def read_bin(name)
       read(name, REG_BINARY)[1]
     end
 
     #
-    # writer
+    # Write data to a registry value named name.
+    # When name is nil, write to the `default' value.
+    #
+    # type is type value. (see Registry::Constants module)
+    # Class of data must be same as which #read
+    # method returns.
     #
     def write(name, type, data)
       case type
@@ -751,6 +700,18 @@ module Win32
       API.SetValue(@hkey, name, type, data, data.length)
     end
 
+    #
+    # Write value to a registry value named name.
+    #
+    # If wtype is specified, the value type is it.
+    # Otherwise, the value type is depend on class of value:
+    # :Integer
+    #   REG_DWORD
+    # :String
+    #   REG_SZ
+    # :Array
+    #   REG_MULTI_SZ
+    #
     def []=(name, rtype, value = nil)
       if value
         write name, rtype, value
@@ -769,26 +730,51 @@ module Win32
       value
     end
 
+    #
+    # Write value to a registry value named name.
+    #
+    # The value type is REG_SZ(write_s), REG_DWORD(write_i), or
+    # REG_BINARY(write_bin).
+    #
     def write_s(name, value)
       write name, REG_SZ, value.to_s
     end
 
+    #
+    # Write value to a registry value named name.
+    #
+    # The value type is REG_SZ(write_s), REG_DWORD(write_i), or
+    # REG_BINARY(write_bin).
+    #
     def write_i(name, value)
       write name, REG_DWORD, value.to_i
     end
 
+    #
+    # Write value to a registry value named name.
+    #
+    # The value type is REG_SZ(write_s), REG_DWORD(write_i), or
+    # REG_BINARY(write_bin).
+    #
     def write_bin(name, value)
       write name, REG_BINARY, value.to_s
     end
 
     #
-    # delete
+    # Delete a registry value named name.
+    # We can not delete the `default' value.
     #
     def delete_value(name)
       API.DeleteValue(@hkey, name)
     end
     alias delete delete_value
 
+    #
+    # Delete a subkey named name and all its values.
+    #
+    # If recursive is false, the subkey must not have subkeys.
+    # Otherwise, this method deletes all subkeys and values recursively.
+    #
     def delete_key(name, recursive = false)
       if recursive
         open(name, KEY_ALL_ACCESS) do |reg|
@@ -812,18 +798,38 @@ module Win32
     end
 
     #
-    # flush
+    # Write all the attributes into the registry file.
     #
     def flush
       API.FlushKey @hkey
     end
 
     #
-    # key information
+    # Returns key information as Array of:
+    # :num_keys
+    #   The number of subkeys.
+    # :max_key_length
+    #   Maximum length of name of subkeys.
+    # :num_values
+    #   The number of values.
+    # :max_value_name_length
+    #   Maximum length of name of values.
+    # :max_value_length
+    #   Maximum length of value of values.
+    # :descriptor_length
+    #   Length of security descriptor.
+    # :wtime
+    #   Last write time as FILETIME(64-bit integer)
+    #
+    # For detail, see RegQueryInfoKey[http://msdn.microsoft.com/library/en-us/sysinfo/base/regqueryinfokey.asp] Win32 API.
     #
     def info
       API.QueryInfoKey(@hkey)
     end
+
+    #
+    # Returns an item of key information.
+    #
     %w[
       num_keys max_key_length
       num_values max_value_name_length max_value_length