From 27886620d85badb44c43cb962ab4960bc55cde24 Mon Sep 17 00:00:00 2001
From: zzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Fri, 3 Oct 2014 23:51:09 +0000
Subject: * ext/openssl/ossl_rand.c: [DOC] Add rdoc for method descriptions  
 By @vipulnsward [Fixes GH-657] https://github.com/ruby/ruby/pull/657

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@47781 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 ChangeLog               |  5 +++++
 ext/openssl/ossl_rand.c | 39 +++++++++++++++++++++++++++++++++++++--
 2 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 9e2053916c..e9275d86ba 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Sat Oct  4 08:49:34 2014  Zachary Scott  <e@zzak.io>
+
+	* ext/openssl/ossl_rand.c: [DOC] Add rdoc for method descriptions
+	  By @vipulnsward [Fixes GH-657] https://github.com/ruby/ruby/pull/657
+
 Sat Oct  4 08:23:48 2014  Zachary Scott  <e@zzak.io>
 
 	* ext/openssl/ossl_rand.c: Use rb_define_module_function instead of
diff --git a/ext/openssl/ossl_rand.c b/ext/openssl/ossl_rand.c
index 5481296c90..0f92c2e884 100644
--- a/ext/openssl/ossl_rand.c
+++ b/ext/openssl/ossl_rand.c
@@ -32,6 +32,7 @@ VALUE eRandomError;
  *  call-seq:
  *     seed(str) -> str
  *
+ * ::seed is equivalent to ::add where +entropy+ is length of +str+.
  */
 static VALUE
 ossl_rand_seed(VALUE self, VALUE str)
@@ -46,6 +47,19 @@ ossl_rand_seed(VALUE self, VALUE str)
  *  call-seq:
  *     add(str, entropy) -> self
  *
+ * Mixes the bytes from +str+ into the Pseudo Random Number Generator(PRNG) state.
+ * Thus, if the data from +str+ are unpredictable to an adversary, this increases the uncertainty about the state
+ * and makes the PRNG output less predictable.
+ * The +entropy+ argument is (the lower bound of) an estimate of how much randomness is contained in +str+,
+ * measured in bytes.
+ *
+ *  Example:
+ *
+ *    pid = $$
+ *    now = Time.now
+ *    ary = [now.to_i, now.nsec, 1000, pid]
+ *    OpenSSL::Random.add(ary.join("").to_s, 0.0)
+ *    OpenSSL::Random.seed(ary.join("").to_s)
  */
 static VALUE
 ossl_rand_add(VALUE self, VALUE str, VALUE entropy)
@@ -60,6 +74,7 @@ ossl_rand_add(VALUE self, VALUE str, VALUE entropy)
  *  call-seq:
  *     load_random_file(filename) -> true
  *
+ * Reads bytes from +filename+ and adds them to the PRNG.
  */
 static VALUE
 ossl_rand_load_file(VALUE self, VALUE filename)
@@ -76,6 +91,8 @@ ossl_rand_load_file(VALUE self, VALUE filename)
  *  call-seq:
  *     write_random_file(filename) -> true
  *
+ * Writes a number of random generated bytes (currently 1024) to +filename+ which can be used to initialize the PRNG by
+ * calling ::load_random_file in a later session.
  */
 static VALUE
 ossl_rand_write_file(VALUE self, VALUE filename)
@@ -89,8 +106,14 @@ ossl_rand_write_file(VALUE self, VALUE filename)
 
 /*
  *  call-seq:
- *     random_bytes(length) -> aString
+ *     -> string
+ *
+ * Generates +string+ with +length+ number of cryptographically strong pseudo-random bytes.
+ *
+ *  Example:
  *
+ *    OpenSSL::Random.random_bytes(12)
+ *    => "..."
  */
 static VALUE
 ossl_rand_bytes(VALUE self, VALUE len)
@@ -108,8 +131,17 @@ ossl_rand_bytes(VALUE self, VALUE len)
 
 /*
  *  call-seq:
- *     pseudo_bytes(length) -> aString
+ *     -> string
+ *
+ * Generates +string+ with +length+ number of pseudo-random bytes.
+ *
+ * Pseudo-random byte sequences generated by ::pseudo_bytes will be unique if they are of sufficient length,
+ * but are not necessarily unpredictable.
+ *
+ *  Example:
  *
+ *    OpenSSL::Random.pseudo_bytes(12)
+ *    => "..."
  */
 static VALUE
 ossl_rand_pseudo_bytes(VALUE self, VALUE len)
@@ -129,6 +161,7 @@ ossl_rand_pseudo_bytes(VALUE self, VALUE len)
  *  call-seq:
  *     egd(filename) -> true
  *
+ * Same as ::egd_bytes but queries 255 bytes by default.
  */
 static VALUE
 ossl_rand_egd(VALUE self, VALUE filename)
@@ -145,6 +178,8 @@ ossl_rand_egd(VALUE self, VALUE filename)
  *  call-seq:
  *     egd_bytes(filename, length) -> true
  *
+ * Queries the entropy gathering daemon EGD on socket path given by +filename+.
+ * Fetches +length+ number of bytes and uses ::add to seed the OpenSSL built-in PRNG.
  */
 static VALUE
 ossl_rand_egd_bytes(VALUE self, VALUE filename, VALUE len)
-- 
cgit v1.2.3