* ext/openssl/lib/openssl/*.rb: [DOC] Document the following:

  - Integer#to_bn
  - OpenSSL::Buffering module
  - Document deprecated OpenSSL::Digest::Digest compatibility class
  - OpenSSL::Config

  These changes were based on a patch by @vbatts via GH-436
  https://github.com/ruby/ruby/pull/436


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

4 files changed, 178 insertions, 5 deletions

diff --git a/ext/openssl/lib/openssl/bn.rb b/ext/openssl/lib/openssl/bn.rb
index db722438e4..0e19c20d34 100644
--- a/ext/openssl/lib/openssl/bn.rb
+++ b/ext/openssl/lib/openssl/bn.rb
@@ -28,6 +28,9 @@ end # OpenSSL
 # Add double dispatch to Integer
 #
 class Integer
+  # Casts an Integer as an OpenSSL::BN
+  #
+  # See `man bn` for more info.
   def to_bn
     OpenSSL::BN::new(self)
   end
diff --git a/ext/openssl/lib/openssl/buffering.rb b/ext/openssl/lib/openssl/buffering.rb
index e40dfee667..bf69ac0988 100644
--- a/ext/openssl/lib/openssl/buffering.rb
+++ b/ext/openssl/lib/openssl/buffering.rb
@@ -18,6 +18,9 @@
 # OpenSSL IO buffering mix-in module.
 #
 # This module allows an OpenSSL::SSL::SSLSocket to behave like an IO.
+#
+# You typically won't use this module directly, you can see it implemented in
+# OpenSSL::SSL::SSLSocket.
 
 module OpenSSL::Buffering
   include Enumerable
@@ -34,6 +37,9 @@ module OpenSSL::Buffering
 
   BLOCK_SIZE = 1024*16
 
+  ##
+  # Creates an instance of OpenSSL's buffering IO module.
+
   def initialize(*args)
     @eof = false
     @rbuffer = ""
diff --git a/ext/openssl/lib/openssl/config.rb b/ext/openssl/lib/openssl/config.rb
index 24a54c91ec..9f5c6affac 100644
--- a/ext/openssl/lib/openssl/config.rb
+++ b/ext/openssl/lib/openssl/config.rb
@@ -13,10 +13,25 @@
 require 'stringio'
 
 module OpenSSL
+  ##
+  # = OpenSSL::Config
+  #
+  # Configuration for the openssl library.
+  #
+  # Many system's installation of openssl library will depend on your system
+  # configuration. See the value of OpenSSL::Config::DEFAULT_CONFIG_FILE for
+  # the location of the file for your host.
+  #
+  # See also http://www.openssl.org/docs/apps/config.html
   class Config
     include Enumerable
 
     class << self
+
+      ##
+      # Parses a given +str+ as a blob that contains configuration for openssl.
+      #
+      # If the source of the IO is a file, then consider using #parse_config.
       def parse(str)
         c = new()
         parse_config(StringIO.new(str)).each do |section, hash|
@@ -25,8 +40,14 @@ module OpenSSL
         c
       end
 
+      ##
+      # load is an alias to ::new
       alias load new
 
+      ##
+      # Parses the configuration data read from +io+, see also #parse.
+      #
+      # Raises a ConfigError on invalid configuration data.
       def parse_config(io)
         begin
           parse_config_lines(io)
@@ -209,6 +230,18 @@ module OpenSSL
       end
     end
 
+    ##
+    # Creates an instance of OpenSSL's configuration class.
+    #
+    # This can be used in contexts like OpenSSL::X509::ExtensionFactory.config=
+    #
+    # If the optional +filename+ parameter is provided, then it is read in and
+    # parsed via #parse_config.
+    #
+    # This can raise IO exceptions based on the access, or availability of the
+    # file. A ConfigError exception may be raised depending on the validity of
+    # the data being configured.
+    #
     def initialize(filename = nil)
       @data = {}
       if filename
@@ -220,6 +253,23 @@ module OpenSSL
       end
     end
 
+    ##
+    # Gets the value of +key+ from the given +section+
+    #
+    # Given the following configurating file being loaded:
+    #
+    #   config = OpenSSL::Config.load('foo.cnf')
+    #     #=> #<OpenSSL::Config sections=["default"]>
+    #   puts config.to_s
+    #     #=> [ default ]
+    #     #   foo=bar
+    #
+    # You can get a specific value from the config if you know the +section+
+    # and +key+ like so:
+    #
+    #   config.get_value('default','foo')
+    #     #=> "bar"
+    #
     def get_value(section, key)
       if section.nil?
         raise TypeError.new('nil not allowed')
@@ -228,7 +278,12 @@ module OpenSSL
       get_key_string(section, key)
     end
 
-    def value(arg1, arg2 = nil)
+    ##
+    #
+    # *Deprecated*
+    #
+    # Use #get_value instead
+    def value(arg1, arg2 = nil) # :nodoc:
       warn('Config#value is deprecated; use Config#get_value')
       if arg2.nil?
         section, key = 'default', arg1
@@ -240,20 +295,84 @@ module OpenSSL
       get_key_string(section, key)
     end
 
+    ##
+    # Set the target +key+ with a given +value+ under a specific +section+.
+    #
+    # Given the following configurating file being loaded:
+    #
+    #   config = OpenSSL::Config.load('foo.cnf')
+    #     #=> #<OpenSSL::Config sections=["default"]>
+    #   puts config.to_s
+    #     #=> [ default ]
+    #     #   foo=bar
+    #
+    # You can set the value of +foo+ under the +default+ section to a new
+    # value:
+    #
+    #   config.add_value('default', 'foo', 'buzz')
+    #     #=> "buzz"
+    #   puts config.to_s
+    #     #=> [ default ]
+    #     #   foo=buzz
+    #
     def add_value(section, key, value)
       check_modify
       (@data[section] ||= {})[key] = value
     end
 
+    ##
+    # Get a specific +section+ from the current configuration
+    #
+    # Given the following configurating file being loaded:
+    #
+    #   config = OpenSSL::Config.load('foo.cnf')
+    #     #=> #<OpenSSL::Config sections=["default"]>
+    #   puts config.to_s
+    #     #=> [ default ]
+    #     #   foo=bar
+    #
+    # You can get a hash of the specific section like so:
+    #
+    #   config['default']
+    #     #=> {"foo"=>"bar"}
+    #
     def [](section)
       @data[section] || {}
     end
 
-    def section(name)
+    ##
+    # Deprecated
+    #
+    # Use #[] instead
+    def section(name) # :nodoc:
       warn('Config#section is deprecated; use Config#[]')
       @data[name] || {}
     end
 
+    ##
+    # Sets a specific +section+ name with a Hash +pairs+
+    #
+    # Given the following configuration being created:
+    #
+    #   config = OpenSSL::Config.new
+    #     #=> #<OpenSSL::Config sections=[]>
+    #   config['default'] = {"foo"=>"bar","baz"=>"buz"}
+    #     #=> {"foo"=>"bar", "baz"=>"buz"}
+    #   puts config.to_s
+    #     #=> [ default ]
+    #     #   foo=bar
+    #     #   baz=buz
+    #
+    # It's important to note that this will essentially merge any of the keys
+    # in +pairs+ with the existing +section+. For example:
+    #
+    #   config['default']
+    #     #=> {"foo"=>"bar", "baz"=>"buz"}
+    #   config['default'] = {"foo" => "changed"}
+    #     #=> {"foo"=>"changed"}
+    #   config['default']
+    #     #=> {"foo"=>"changed", "baz"=>"buz"}
+    #
     def []=(section, pairs)
       check_modify
       @data[section] ||= {}
@@ -262,10 +381,38 @@ module OpenSSL
       end
     end
 
+    ##
+    # Get the names of all sections in the current configuration
     def sections
       @data.keys
     end
 
+    ##
+    # Get the parsable form of the current configuration
+    #
+    # Given the following configuration being created:
+    #
+    #   config = OpenSSL::Config.new
+    #     #=> #<OpenSSL::Config sections=[]>
+    #   config['default'] = {"foo"=>"bar","baz"=>"buz"}
+    #     #=> {"foo"=>"bar", "baz"=>"buz"}
+    #   puts config.to_s
+    #     #=> [ default ]
+    #     #   foo=bar
+    #     #   baz=buz
+    #
+    # You can parse get the serialized configuration using #to_s and then parse
+    # it later:
+    #
+    #   serialized_config = config.to_s
+    #   # much later...
+    #   new_config = OpenSSL::Config.parse(serialized_config)
+    #     #=> #<OpenSSL::Config sections=["default"]>
+    #   puts new_config
+    #     #=> [ default ]
+    #         foo=bar
+    #         baz=buz
+    #
     def to_s
       ary = []
       @data.keys.sort.each do |section|
@@ -278,6 +425,15 @@ module OpenSSL
       ary.join
     end
 
+    ##
+    # For a block.
+    #
+    # Receive the section and its pairs for the current configuration.
+    #
+    #   config.each do |section, key, value|
+    #     # ...
+    #   end
+    #
     def each
       @data.each do |section, hash|
         hash.each do |key, value|
@@ -286,13 +442,16 @@ module OpenSSL
       end
     end
 
+    ##
+    # String representation of this configuration object, including the class
+    # name and its sections.
     def inspect
       "#<#{self.class.name} sections=#{sections.inspect}>"
     end
 
   protected
 
-    def data
+    def data # :nodoc:
       @data
     end
 
diff --git a/ext/openssl/lib/openssl/digest.rb b/ext/openssl/lib/openssl/digest.rb
index f2a47bfdf9..80b58af5da 100644
--- a/ext/openssl/lib/openssl/digest.rb
+++ b/ext/openssl/lib/openssl/digest.rb
@@ -59,8 +59,13 @@ module OpenSSL
       const_set(name, klass)
     }
 
-    # This class is only provided for backwards compatibility.  Use OpenSSL::Digest in the future.
-    class Digest < Digest
+    # This class is only provided for backwards compatibility.
+    #
+    # Use OpenSSL::Digest in the future.
+    class Digest < Digest # :nodoc:
+      # Deprecated.
+      #
+      # See OpenSSL::Digest.new
       def initialize(*args)
         # add warning
         super(*args)