zzak	2014-10-04 08:51:09 +0900 (Sat, 04 Oct 2014)

  New Revision: 47781

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=47781

  Log:
    * ext/openssl/ossl_rand.c: [DOC] Add rdoc for method descriptions
      By @vipulnsward [Fixes GH-657] https://github.com/ruby/ruby/pull/657

  Modified files:
    trunk/ChangeLog
    trunk/ext/openssl/ossl_rand.c
Index: ChangeLog
===================================================================
--- ChangeLog	(revision 47780)
+++ ChangeLog	(revision 47781)
@@ -1,3 +1,8 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1
+Sat Oct  4 08:49:34 2014  Zachary Scott  <e@z...>
+
+	* 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@z...>
 
 	* ext/openssl/ossl_rand.c: Use rb_define_module_function instead of
Index: ext/openssl/ossl_rand.c
===================================================================
--- ext/openssl/ossl_rand.c	(revision 47780)
+++ ext/openssl/ossl_rand.c	(revision 47781)
@@ -32,6 +32,7 @@ VALUE eRandomError; https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_rand.c#L32
  *  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) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_rand.c#L47
  *  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, VAL https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_rand.c#L74
  *  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 fi https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_rand.c#L91
  *  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 f https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_rand.c#L106
 
 /*
  *  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) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_rand.c#L131
 
 /*
  *  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 https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_rand.c#L161
  *  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 https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_rand.c#L178
  *  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)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/