Merge branch 'topic/fix-rdoc-markup'

* topic/fix-rdoc-markup:
  Fix RDoc markup
  Revert r57690 except for read_nonblock
  [DOC] mark up literals
  [DOC] keyword argument _exception_
  [DOC] {read,write}_nonblock with exception: false

Author: rhenium

ext/openssl/ossl.c

@@ -328,7 +328,8 @@ ossl_clear_error(void)
  *
  * See any remaining errors held in queue.
  *
- * Any errors you see here are probably due to a bug in ruby's OpenSSL implementation.
+ * Any errors you see here are probably due to a bug in Ruby's OpenSSL
+ * implementation.
  */
 VALUE
 ossl_get_errors(void)
@@ -452,7 +453,7 @@ mem_check_start(VALUE self)
  * Prints detected memory leaks to standard error. This cleans the global state
  * up thus you cannot use any methods of the library after calling this.
  *
- * Returns true if leaks detected, false otherwise.
+ * Returns +true+ if leaks detected, +false+ otherwise.
  *
  * This is available only when built with a capable OpenSSL and --enable-debug
  * configure option.
@@ -568,7 +569,7 @@ static void Init_ossl_locks(void)
 
 /*
  * OpenSSL provides SSL, TLS and general purpose cryptography.  It wraps the
- * OpenSSL[http://www.openssl.org/] library.
+ * OpenSSL[https://www.openssl.org/] library.
  *
  * = Examples
  *

ext/openssl/ossl_asn1.c

@@ -176,16 +176,15 @@ ossl_bn_alloc(VALUE klass)
     return obj;
 }
 
-/* Document-method: OpenSSL::BN.new
- *
+/*
  * call-seq:
  *    OpenSSL::BN.new => aBN
  *    OpenSSL::BN.new(bn) => aBN
  *    OpenSSL::BN.new(integer) => aBN
  *    OpenSSL::BN.new(string) => aBN
  *    OpenSSL::BN.new(string, 0 | 2 | 10 | 16) => aBN
  *
- * Construct a new OpenSSL BigNum object.
+ * Construct a new OpenSSL BIGNUM object.
  */
 static VALUE
 ossl_bn_initialize(int argc, VALUE *argv, VALUE self)
@@ -250,7 +249,7 @@ ossl_bn_initialize(int argc, VALUE *argv, VALUE self)
  *    bn.to_s(base) => string
  *
  * === Parameters
- * * +base+ - integer
+ * * _base_ - Integer
  *   Valid values:
  *   * 0 - MPI
  *   * 2 - binary
@@ -513,7 +512,6 @@ BIGNUM_2c(mod_sqr)
 BIGNUM_2c(mod_inverse)
 
 /*
- * Document-method: OpenSSL::BN#/
  * call-seq:
  *    bn1 / bn2 => [result, remainder]
  *
@@ -629,12 +627,11 @@ BIGNUM_BIT(clear_bit)
  */
 BIGNUM_BIT(mask_bits)
 
-/* Document-method: OpenSSL::BN#bit_set?
+/*
  * call-seq:
  *   bn.bit_set?(bit) => true | false
  *
- * Returns boolean of whether +bit+ is set.
- * Bitwise operations for openssl BIGNUMs.
+ * Tests bit _bit_ in _bn_ and returns +true+ if set, +false+ if not set.
  */
 static VALUE
 ossl_bn_is_bit_set(VALUE self, VALUE bit)
@@ -789,15 +786,15 @@ BIGNUM_RAND_RANGE(pseudo_rand)
  * call-seq:
  *    BN.generate_prime(bits, [, safe [, add [, rem]]]) => bn
  *
- * Generates a random prime number of bit length +bits+. If +safe+ is true,
- * generates a safe prime. If +add+ is specified, generates a prime that
+ * Generates a random prime number of bit length _bits_. If _safe_ is set to
+ * +true+, generates a safe prime. If _add_ is specified, generates a prime that
  * fulfills condition <tt>p % add = rem</tt>.
  *
  * === Parameters
- * * +bits+ - integer
- * * +safe+ - boolean
- * * +add+ - BN
- * * +rem+ - BN
+ * * _bits_ - integer
+ * * _safe_ - boolean
+ * * _add_ - BN
+ * * _rem_ - BN
  */
 static VALUE
 ossl_bn_s_generate_prime(int argc, VALUE *argv, VALUE klass)
@@ -934,7 +931,7 @@ BIGNUM_CMP(ucmp)
  *  call-seq:
  *     bn == obj => true or false
  *
- *  Returns +true+ only if +obj+ has the same value as +bn+. Contrast this
+ *  Returns +true+ only if _obj_ has the same value as _bn_. Contrast this
  *  with OpenSSL::BN#eql?, which requires obj to be OpenSSL::BN.
  */
 static VALUE
@@ -959,7 +956,7 @@ ossl_bn_eq(VALUE self, VALUE other)
  *     bn.eql?(obj) => true or false
  *
  *  Returns <code>true</code> only if <i>obj</i> is a
- *  <code>OpenSSL::BN</code> with the same value as <i>big</i>. Contrast this
+ *  <code>OpenSSL::BN</code> with the same value as <i>bn</i>. Contrast this
  *  with OpenSSL::BN#==, which performs type conversions.
  */
 static VALUE
@@ -1010,12 +1007,12 @@ ossl_bn_hash(VALUE self)
  *    bn.prime? => true | false
  *    bn.prime?(checks) => true | false
  *
- * Performs a Miller-Rabin probabilistic primality test with +checks+
- * iterations. If +nchecks+ is not specified, a number of iterations is used
+ * Performs a Miller-Rabin probabilistic primality test with _checks_
+ * iterations. If _checks_ is not specified, a number of iterations is used
  * that yields a false positive rate of at most 2^-80 for random input.
  *
  * === Parameters
- * * +checks+ - integer
+ * * _checks_ - integer
  */
 static VALUE
 ossl_bn_is_prime(int argc, VALUE *argv, VALUE self)
@@ -1050,8 +1047,8 @@ ossl_bn_is_prime(int argc, VALUE *argv, VALUE self)
  * first attempts trial divisions with some small primes.
  *
  * === Parameters
- * * +checks+ - integer
- * * +trial_div+ - boolean
+ * * _checks_ - integer
+ * * _trial_div_ - boolean
  */
 static VALUE
 ossl_bn_is_prime_fasttest(int argc, VALUE *argv, VALUE self)

ext/openssl/ossl_bn.c

@@ -108,7 +108,7 @@ ossl_cipher_alloc(VALUE klass)
  *  call-seq:
  *     Cipher.new(string) -> cipher
  *
- *  The string must contain a valid cipher name like "AES-128-CBC" or "3DES".
+ *  The string must be a valid cipher name like "AES-128-CBC" or "3DES".
  *
  *  A list of cipher names is available by calling OpenSSL::Cipher.ciphers.
  */
@@ -296,9 +296,9 @@ ossl_cipher_decrypt(int argc, VALUE *argv, VALUE self)
  *  OpenSSL::PKCS5 instead.
  *
  *  === Parameters
- *  * +salt+ must be an 8 byte string if provided.
- *  * +iterations+ is an integer with a default of 2048.
- *  * +digest+ is a Digest object that defaults to 'MD5'
+ *  * _salt_ must be an 8 byte string if provided.
+ *  * _iterations_ is an integer with a default of 2048.
+ *  * _digest_ is a Digest object that defaults to 'MD5'
  *
  *  A minimum of 1000 iterations is recommended.
  *
@@ -365,12 +365,12 @@ ossl_cipher_update_long(EVP_CIPHER_CTX *ctx, unsigned char *out, long *out_len_p
  *     cipher.update(data [, buffer]) -> string or buffer
  *
  *  Encrypts data in a streaming fashion. Hand consecutive blocks of data
- *  to the +update+ method in order to encrypt it. Returns the encrypted
+ *  to the #update method in order to encrypt it. Returns the encrypted
  *  data chunk. When done, the output of Cipher#final should be additionally
  *  added to the result.
  *
- *  If +buffer+ is given, the encryption/decryption result will be written to
- *  it. +buffer+ will be resized automatically.
+ *  If _buffer_ is given, the encryption/decryption result will be written to
+ *  it. _buffer_ will be resized automatically.
  */
 static VALUE
 ossl_cipher_update(int argc, VALUE *argv, VALUE self)
@@ -587,8 +587,8 @@ ossl_cipher_set_auth_data(VALUE self, VALUE data)
  *  Gets the authentication tag generated by Authenticated Encryption Cipher
  *  modes (GCM for example). This tag may be stored along with the ciphertext,
  *  then set on the decryption cipher to authenticate the contents of the
- *  ciphertext against changes. If the optional integer parameter +tag_len+ is
- *  given, the returned tag will be +tag_len+ bytes long. If the parameter is
+ *  ciphertext against changes. If the optional integer parameter _tag_len_ is
+ *  given, the returned tag will be _tag_len_ bytes long. If the parameter is
  *  omitted, the default length of 16 bytes or the length previously set by
  *  #auth_tag_len= will be used. For maximum security, the longest possible
  *  should be chosen.
@@ -1004,9 +1004,9 @@ Init_ossl_cipher(void)
      * encryption and later decryption, the OpenSSL library still requires a
      * value to be set - "" may be used in case none is available.
      *
-     * An example using the GCM (Galois/Counter Mode). You have 16 bytes +key+,
-     * 12 bytes (96 bits) +nonce+ and the associated data +auth_data+. Be sure
-     * not to reuse the +key+ and +nonce+ pair. Reusing an nonce ruins the
+     * An example using the GCM (Galois/Counter Mode). You have 16 bytes _key_,
+     * 12 bytes (96 bits) _nonce_ and the associated data _auth_data_. Be sure
+     * not to reuse the _key_ and _nonce_ pair. Reusing an nonce ruins the
      * security gurantees of GCM mode.
      *
      *   cipher = OpenSSL::Cipher::AES.new(128, :GCM).encrypt
@@ -1017,8 +1017,8 @@ Init_ossl_cipher(void)
      *   encrypted = cipher.update(data) + cipher.final
      *   tag = cipher.auth_tag # produces 16 bytes tag by default
      *
-     * Now you are the receiver. You know the +key+ and have received +nonce+,
-     * +auth_data+, +encrypted+ and +tag+ through an untrusted network. Note
+     * Now you are the receiver. You know the _key_ and have received _nonce_,
+     * _auth_data_, _encrypted_ and _tag_ through an untrusted network. Note
      * that GCM accepts an arbitrary length tag between 1 and 16 bytes. You may
      * additionally need to check that the received tag has the correct length,
      * or you allow attackers to forge a valid single byte tag for the tampered

ext/openssl/ossl_cipher.c

@@ -106,15 +106,15 @@ VALUE ossl_digest_update(VALUE, VALUE);
  *  call-seq:
  *     Digest.new(string [, data]) -> Digest
  *
- * Creates a Digest instance based on +string+, which is either the ln
+ * Creates a Digest instance based on _string_, which is either the ln
  * (long name) or sn (short name) of a supported digest algorithm.
  *
- * If +data+ (a +String+) is given, it is used as the initial input to the
+ * If _data_ (a String) is given, it is used as the initial input to the
  * Digest instance, i.e.
  *
  *   digest = OpenSSL::Digest.new('sha256', 'digestdata')
  *
- * is equal to
+ * is equivalent to
  *
  *   digest = OpenSSL::Digest.new('sha256')
  *   digest.update('digestdata')