Fix RDoc styletopic/rdoc-fixes

30 files changed, 190 insertions, 97 deletions

diff --git a/ext/openssl/ossl.c b/ext/openssl/ossl.c
index 83baa7b6..42587722 100644
--- a/ext/openssl/ossl.c
+++ b/ext/openssl/ossl.c
@@ -483,9 +483,8 @@ ossl_debug_set(VALUE self, VALUE val)
  * so otherwise will result in an error.
  *
  * === Examples
- *
- * OpenSSL.fips_mode = true   # turn FIPS mode on
- * OpenSSL.fips_mode = false  # and off again
+ *   OpenSSL.fips_mode = true   # turn FIPS mode on
+ *   OpenSSL.fips_mode = false  # and off again
  */
 static VALUE
 ossl_fips_mode_set(VALUE self, VALUE enabled)
@@ -910,7 +909,7 @@ static void Init_ossl_locks(void)
  *   ca_key = OpenSSL::PKey::RSA.new 2048
  *   pass_phrase = 'my secure pass phrase goes here'
  *
- *   cipher = OpenSSL::Cipher::Cipher.new 'AES-128-CBC'
+ *   cipher = OpenSSL::Cipher.new 'AES-128-CBC'
  *
  *   open 'ca_key.pem', 'w', 0400 do |io|
  *     io.write ca_key.export(cipher, pass_phrase)
@@ -1160,11 +1159,14 @@ Init_openssl(void)
     /*
      * Boolean indicating whether OpenSSL is FIPS-enabled or not
      */
+    rb_define_const(mOSSL, "OPENSSL_FIPS",
 #ifdef OPENSSL_FIPS
-    rb_define_const(mOSSL, "OPENSSL_FIPS", Qtrue);
+		    Qtrue
 #else
-    rb_define_const(mOSSL, "OPENSSL_FIPS", Qfalse);
+		    Qfalse
 #endif
+		   );
+
     rb_define_module_function(mOSSL, "fips_mode=", ossl_fips_mode_set, 1);
 
     /*
diff --git a/ext/openssl/ossl_asn1.c b/ext/openssl/ossl_asn1.c
index cbedd59e..eb48aa5b 100644
--- a/ext/openssl/ossl_asn1.c
+++ b/ext/openssl/ossl_asn1.c
@@ -1471,7 +1471,8 @@ Init_ossl_asn1(void)
     int i;
 
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
 #endif
 
     sUNIVERSAL = rb_intern("UNIVERSAL");
@@ -1806,10 +1807,6 @@ Init_ossl_asn1(void)
      * it is not typically allocated this way, but rather that are received from
      * parsed ASN1 encodings.
      *
-     * While OpenSSL::ASN1::ObjectId.new will allocate a new ObjectId, it is
-     * not typically allocated this way, but rather that are received from
-     * parsed ASN1 encodings.
-     *
      * === Additional attributes
      * * +sn+: the short name as defined in <openssl/objects.h>.
      * * +ln+: the long name as defined in <openssl/objects.h>.
diff --git a/ext/openssl/ossl_bn.c b/ext/openssl/ossl_bn.c
index 6a0a21eb..bbbc5f04 100644
--- a/ext/openssl/ossl_bn.c
+++ b/ext/openssl/ossl_bn.c
@@ -52,8 +52,6 @@ VALUE cBN;
 
 /* Document-class: OpenSSL::BNError
  *
- * BNError < OpenSSLError
- *
  * Generic Error for all of OpenSSL::BN (big num)
  */
 VALUE eBNError;
@@ -135,6 +133,7 @@ ossl_bn_alloc(VALUE klass)
 
 /* Document-method: OpenSSL::BN.new
  *
+ * call-seq:
  *    OpenSSL::BN.new => aBN
  *    OpenSSL::BN.new(bn) => aBN
  *    OpenSSL::BN.new(integer) => aBN
@@ -239,11 +238,11 @@ ossl_bn_initialize(int argc, VALUE *argv, VALUE self)
  *
  * === Parameters
  * * +base+ - integer
- * * * Valid values:
- * * * * 0 - MPI
- * * * * 2 - binary
- * * * * 10 - the default
- * * * * 16 - hex
+ *   Valid values:
+ *   * 0 - MPI
+ *   * 2 - binary
+ *   * 10 - the default
+ *   * 16 - hex
  */
 static VALUE
 ossl_bn_to_s(int argc, VALUE *argv, VALUE self)
@@ -346,18 +345,21 @@ ossl_bn_coerce(VALUE self, VALUE other)
 
 /*
  * Document-method: OpenSSL::BN#zero?
+ * call-seq:
  *   bn.zero? => true | false
  */
 BIGNUM_BOOL1(is_zero)
 
 /*
  * Document-method: OpenSSL::BN#one?
+ * call-seq:
  *   bn.one? => true | false
  */
 BIGNUM_BOOL1(is_one)
 
 /*
  * Document-method: OpenSSL::BN#odd?
+ * call-seq:
  *   bn.odd? => true | false
  */
 BIGNUM_BOOL1(is_odd)
@@ -383,6 +385,7 @@ BIGNUM_BOOL1(is_odd)
 
 /*
  * Document-method: OpenSSL::BN#sqr
+ * call-seq:
  *   bn.sqr => aBN
  */
 BIGNUM_1c(sqr)
@@ -408,12 +411,14 @@ BIGNUM_1c(sqr)
 
 /*
  * Document-method: OpenSSL::BN#+
+ * call-seq:
  *   bn + bn2 => aBN
  */
 BIGNUM_2(add)
 
 /*
  * Document-method: OpenSSL::BN#-
+ * call-seq:
  *   bn - bn2 => aBN
  */
 BIGNUM_2(sub)
@@ -439,42 +444,49 @@ BIGNUM_2(sub)
 
 /*
  * Document-method: OpenSSL::BN#*
+ * call-seq:
  *   bn * bn2 => aBN
  */
 BIGNUM_2c(mul)
 
 /*
  * Document-method: OpenSSL::BN#%
+ * call-seq:
  *   bn % bn2 => aBN
  */
 BIGNUM_2c(mod)
 
 /*
  * Document-method: OpenSSL::BN#**
+ * call-seq:
  *   bn ** bn2 => aBN
  */
 BIGNUM_2c(exp)
 
 /*
  * Document-method: OpenSSL::BN#gcd
+ * call-seq:
  *   bn.gcd(bn2) => aBN
  */
 BIGNUM_2c(gcd)
 
 /*
  * Document-method: OpenSSL::BN#mod_sqr
+ * call-seq:
  *   bn.mod_sqr(bn2) => aBN
  */
 BIGNUM_2c(mod_sqr)
 
 /*
  * Document-method: OpenSSL::BN#mod_inverse
+ * call-seq:
  *   bn.mod_inverse(bn2) => aBN
  */
 BIGNUM_2c(mod_inverse)
 
 /*
  * Document-method: OpenSSL::BN#/
+ * call-seq:
  *    bn1 / bn2 => [result, remainder]
  *
  * Division of OpenSSL::BN instances
@@ -529,24 +541,28 @@ ossl_bn_div(VALUE self, VALUE other)
 
 /*
  * Document-method: OpenSSL::BN#mod_add
+ * call-seq:
  *   bn.mod_add(bn1, bn2) -> aBN
  */
 BIGNUM_3c(mod_add)
 
 /*
  * Document-method: OpenSSL::BN#mod_sub
+ * call-seq:
  *   bn.mod_sub(bn1, bn2) -> aBN
  */
 BIGNUM_3c(mod_sub)
 
 /*
  * Document-method: OpenSSL::BN#mod_mul
+ * call-seq:
  *   bn.mod_mul(bn1, bn2) -> aBN
  */
 BIGNUM_3c(mod_mul)
 
 /*
  * Document-method: OpenSSL::BN#mod_exp
+ * call-seq:
  *   bn.mod_exp(bn1, bn2) -> aBN
  */
 BIGNUM_3c(mod_exp)
@@ -565,29 +581,31 @@ BIGNUM_3c(mod_exp)
 
 /*
  * Document-method: OpenSSL::BN#set_bit!
+ * call-seq:
  *   bn.set_bit!(bit) -> self
  */
 BIGNUM_BIT(set_bit)
 
 /*
  * Document-method: OpenSSL::BN#clear_bit!
+ * call-seq:
  *   bn.clear_bit!(bit) -> self
  */
 BIGNUM_BIT(clear_bit)
 
 /*
  * Document-method: OpenSSL::BN#mask_bit!
+ * call-seq:
  *   bn.mask_bit!(bit) -> self
  */
 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.
- *
- *    bn.bit_set?(bit) => true | false
- *
  */
 static VALUE
 ossl_bn_is_bit_set(VALUE self, VALUE bit)
@@ -653,12 +671,14 @@ BIGNUM_SHIFT(rshift)
 
 /*
  * Document-method: OpenSSL::BN#lshift!
+ * call-seq:
  *   bn.lshift!(bits) -> self
  */
 BIGNUM_SELF_SHIFT(lshift)
 
 /*
  * Document-method: OpenSSL::BN#rshift!
+ * call-seq:
  *   bn.rshift!(bits) -> self
  */
 BIGNUM_SELF_SHIFT(rshift)
@@ -722,6 +742,7 @@ BIGNUM_RAND(pseudo_rand)
 
 /*
  * Document-method: OpenSSL::BN.rand_range
+ * call-seq:
  *   BN.rand_range(range) -> aBN
  *
  */
@@ -729,6 +750,7 @@ BIGNUM_RAND_RANGE(rand)
 
 /*
  * Document-method: OpenSSL::BN.pseudo_rand_range
+ * call-seq:
  *   BN.pseudo_rand_range(range) -> aBN
  *
  */
@@ -790,12 +812,14 @@ ossl_bn_s_generate_prime(int argc, VALUE *argv, VALUE klass)
 
 /*
  * Document-method: OpenSSL::BN#num_bytes
+ * call-seq:
  *   bn.num_bytes => integer
  */
 BIGNUM_NUM(num_bytes)
 
 /*
  * Document-method: OpenSSL::BN#num_bits
+ * call-seq:
  *   bn.num_bits => integer
  */
 BIGNUM_NUM(num_bits)
@@ -829,16 +853,19 @@ ossl_bn_copy(VALUE self, VALUE other)
 
 /*
  * Document-method: OpenSSL::BN#cmp
+ * call-seq:
  *   bn.cmp(bn2) => integer
  */
 /*
  * Document-method: OpenSSL::BN#<=>
+ * call-seq:
  *   bn <=> bn2 => integer
  */
 BIGNUM_CMP(cmp)
 
 /*
  * Document-method: OpenSSL::BN#ucmp
+ * call-seq:
  *   bn.ucmp(bn2) => integer
  */
 BIGNUM_CMP(ucmp)
@@ -921,9 +948,9 @@ 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
- *  that yields a false positive rate of at most 2^-80 for random input.
+ * Performs a Miller-Rabin probabilistic primality test with +checks+
+ * iterations. If +nchecks+ 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
@@ -957,8 +984,8 @@ ossl_bn_is_prime(int argc, VALUE *argv, VALUE self)
  *    bn.prime_fasttest?(checks) => true | false
  *    bn.prime_fasttest?(checks, trial_div) => true | false
  *
- *  Performs a Miller-Rabin primality test. This is same as #prime? except this
- *  first attempts trial divisions with some small primes.
+ * Performs a Miller-Rabin primality test. This is same as #prime? except this
+ * first attempts trial divisions with some small primes.
  *
  * === Parameters
  * * +checks+ - integer
@@ -1001,7 +1028,8 @@ void
 Init_ossl_bn(void)
 {
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
 #endif
 
     if (!(ossl_bn_ctx = BN_CTX_new())) {
diff --git a/ext/openssl/ossl_cipher.c b/ext/openssl/ossl_cipher.c
index be7a0321..76b0aae9 100644
--- a/ext/openssl/ossl_cipher.c
+++ b/ext/openssl/ossl_cipher.c
@@ -730,7 +730,8 @@ void
 Init_ossl_cipher(void)
 {
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
 #endif
 
     /* Document-class: OpenSSL::Cipher
diff --git a/ext/openssl/ossl_config.c b/ext/openssl/ossl_config.c
index 4e00fbe4..fd76415a 100644
--- a/ext/openssl/ossl_config.c
+++ b/ext/openssl/ossl_config.c
@@ -71,6 +71,12 @@ void
 Init_ossl_config(void)
 {
     char *default_config_file;
+
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+#endif
+
     eConfigError = rb_define_class_under(mOSSL, "ConfigError", eOSSLError);
     cConfig = rb_define_class_under(mOSSL, "Config", rb_cObject);
 
diff --git a/ext/openssl/ossl_digest.c b/ext/openssl/ossl_digest.c
index d137dc57..317083fe 100644
--- a/ext/openssl/ossl_digest.c
+++ b/ext/openssl/ossl_digest.c
@@ -310,7 +310,8 @@ Init_ossl_digest(void)
     rb_require("digest");
 
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
 #endif
 
     /* Document-class: OpenSSL::Digest
diff --git a/ext/openssl/ossl_engine.c b/ext/openssl/ossl_engine.c
index 3abc44b3..1da8430f 100644
--- a/ext/openssl/ossl_engine.c
+++ b/ext/openssl/ossl_engine.c
@@ -161,8 +161,6 @@ ossl_engine_s_load(int argc, VALUE *argv, VALUE klass)
  * OpenSSL::Engine.load. However, running cleanup before exit is recommended.
  *
  * Note that this is needed and works only in OpenSSL < 1.1.0.
- *
- * See also, https://www.openssl.org/docs/crypto/engine.html
  */
 static VALUE
 ossl_engine_s_cleanup(VALUE self)
@@ -531,6 +529,11 @@ ossl_engine_inspect(VALUE self)
 void
 Init_ossl_engine(void)
 {
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+#endif
+
     cEngine = rb_define_class_under(mOSSL, "Engine", rb_cObject);
     eEngineError = rb_define_class_under(cEngine, "EngineError", eOSSLError);
 
diff --git a/ext/openssl/ossl_hmac.c b/ext/openssl/ossl_hmac.c
index bb4b5784..a0b05f40 100644
--- a/ext/openssl/ossl_hmac.c
+++ b/ext/openssl/ossl_hmac.c
@@ -348,8 +348,8 @@ void
 Init_ossl_hmac(void)
 {
 #if 0
-    /* :nodoc: */
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
 #endif
 
     eHMACError = rb_define_class_under(mOSSL, "HMACError", eOSSLError);
diff --git a/ext/openssl/ossl_ns_spki.c b/ext/openssl/ossl_ns_spki.c
index e93b1b0a..2f7845b6 100644
--- a/ext/openssl/ossl_ns_spki.c
+++ b/ext/openssl/ossl_ns_spki.c
@@ -380,7 +380,8 @@ void
 Init_ossl_ns_spki(void)
 {
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
 #endif
 
     mNetscape = rb_define_module_under(mOSSL, "Netscape");
diff --git a/ext/openssl/ossl_ocsp.c b/ext/openssl/ossl_ocsp.c
index c0f2dfef..40d58412 100644
--- a/ext/openssl/ossl_ocsp.c
+++ b/ext/openssl/ossl_ocsp.c
@@ -1639,6 +1639,11 @@ ossl_ocspcid_to_der(VALUE self)
 void
 Init_ossl_ocsp(void)
 {
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+#endif
+
     /*
      * OpenSSL::OCSP implements Online Certificate Status Protocol requests
      * and responses.
diff --git a/ext/openssl/ossl_pkcs12.c b/ext/openssl/ossl_pkcs12.c
index 5f849723..43fc5e51 100644
--- a/ext/openssl/ossl_pkcs12.c
+++ b/ext/openssl/ossl_pkcs12.c
@@ -74,8 +74,8 @@ ossl_pkcs12_s_allocate(VALUE klass)
  * * +name+ - A string describing the key.
  * * +key+ - Any PKey.
  * * +cert+ - A X509::Certificate.
- * * * The public_key portion of the certificate must contain a valid public key.
- * * * The not_before and not_after fields must be filled in.
+ *   * The public_key portion of the certificate must contain a valid public key.
+ *   * The not_before and not_after fields must be filled in.
  * * +ca+ - An optional array of X509::Certificate's.
  * * +key_pbe+ - string
  * * +cert_pbe+ - string
@@ -216,6 +216,11 @@ ossl_pkcs12_to_der(VALUE self)
 void
 Init_ossl_pkcs12(void)
 {
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+#endif
+
     /*
      * Defines a file format commonly used to store private keys with
      * accompanying public key certificates, protected with a password-based
diff --git a/ext/openssl/ossl_pkcs5.c b/ext/openssl/ossl_pkcs5.c
index 56ed65fb..47c5bfa3 100644
--- a/ext/openssl/ossl_pkcs5.c
+++ b/ext/openssl/ossl_pkcs5.c
@@ -18,7 +18,7 @@ VALUE ePKCS5;
  * * +keylen+ - integer
  * * +digest+ - a string or OpenSSL::Digest object.
  *
- * Available in OpenSSL 0.9.4.
+ * Available in OpenSSL >= 1.0.0.
  *
  * Digests other than SHA1 may not be supported by other cryptography libraries.
  */
@@ -60,7 +60,7 @@ ossl_pkcs5_pbkdf2_hmac(VALUE self, VALUE pass, VALUE salt, VALUE iter, VALUE key
  *
  * This method is available in almost any version of OpenSSL.
  *
- * Conforms to rfc2898.
+ * Conforms to RFC 2898.
  */
 static VALUE
 ossl_pkcs5_pbkdf2_hmac_sha1(VALUE self, VALUE pass, VALUE salt, VALUE iter, VALUE keylen)
@@ -84,14 +84,10 @@ ossl_pkcs5_pbkdf2_hmac_sha1(VALUE self, VALUE pass, VALUE salt, VALUE iter, VALU
 void
 Init_ossl_pkcs5(void)
 {
-    /*
-     * Password-based Encryption
-     *
-     */
-
-    #if 0
-	mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
-    #endif
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+#endif
 
     /* Document-class: OpenSSL::PKCS5
      *
@@ -104,7 +100,7 @@ Init_ossl_pkcs5(void)
      *
      * PKCS5 offers support for PBKDF2 with an OpenSSL::Digest::SHA1-based
      * HMAC, or an arbitrary Digest if the underlying version of OpenSSL
-     * already supports it (>= 0.9.4).
+     * already supports it (>= 1.0.0).
      *
      * === Parameters
      * ==== Password
diff --git a/ext/openssl/ossl_pkcs7.c b/ext/openssl/ossl_pkcs7.c
index 5b7c07de..31f94c16 100644
--- a/ext/openssl/ossl_pkcs7.c
+++ b/ext/openssl/ossl_pkcs7.c
@@ -1054,6 +1054,11 @@ ossl_pkcs7ri_get_enc_key(VALUE self)
 void
 Init_ossl_pkcs7(void)
 {
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+#endif
+
     cPKCS7 = rb_define_class_under(mOSSL, "PKCS7", rb_cObject);
     ePKCS7Error = rb_define_class_under(cPKCS7, "PKCS7Error", eOSSLError);
     rb_define_singleton_method(cPKCS7, "read_smime", ossl_pkcs7_s_read_smime, 1);
diff --git a/ext/openssl/ossl_pkey.c b/ext/openssl/ossl_pkey.c
index 4ae8e14e..35e75d9f 100644
--- a/ext/openssl/ossl_pkey.c
+++ b/ext/openssl/ossl_pkey.c
@@ -128,11 +128,11 @@ ossl_pkey_new_from_file(VALUE filename)
  *
  * === Parameters
  * * +string+ is a DER- or PEM-encoded string containing an arbitrary private
- * or public key.
+ *   or public key.
  * * +file+ is an instance of +File+ containing a DER- or PEM-encoded
- * arbitrary private or public key.
+ *   arbitrary private or public key.
  * * +pwd+ is an optional password in case +string+ or +file+ is an encrypted
- * PEM resource.
+ *   PEM resource.
  */
 static VALUE
 ossl_pkey_new_from_data(int argc, VALUE *argv, VALUE self)
@@ -352,7 +352,8 @@ void
 Init_ossl_pkey(void)
 {
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
 #endif
 
     /* Document-module: OpenSSL::PKey
diff --git a/ext/openssl/ossl_pkey_dh.c b/ext/openssl/ossl_pkey_dh.c
index 139af152..b6cebef8 100644
--- a/ext/openssl/ossl_pkey_dh.c
+++ b/ext/openssl/ossl_pkey_dh.c
@@ -560,8 +560,9 @@ void
 Init_ossl_dh(void)
 {
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL and mPKey */
     mPKey = rb_define_module_under(mOSSL, "PKey");
+    cPKey = rb_define_class_under(mPKey, "PKey", rb_cObject);
+    ePKeyError = rb_define_class_under(mPKey, "PKeyError", eOSSLError);
 #endif
 
     /* Document-class: OpenSSL::PKey::DHError
@@ -578,15 +579,15 @@ Init_ossl_dh(void)
      * on.
      *
      * === Accessor methods for the Diffie-Hellman parameters
-     * * DH#p
-     * The prime (an OpenSSL::BN) of the Diffie-Hellman parameters.
-     * * DH#g
-     * The generator (an OpenSSL::BN) g of the Diffie-Hellman parameters.
-     * * DH#pub_key
-     * The per-session public key (an OpenSSL::BN) matching the private key.
-     * This needs to be passed to DH#compute_key.
-     * * DH#priv_key
-     * The per-session private key, an OpenSSL::BN.
+     * DH#p::
+     *   The prime (an OpenSSL::BN) of the Diffie-Hellman parameters.
+     * DH#g::
+     *   The generator (an OpenSSL::BN) g of the Diffie-Hellman parameters.
+     * DH#pub_key::
+     *   The per-session public key (an OpenSSL::BN) matching the private key.
+     *   This needs to be passed to DH#compute_key.
+     * DH#priv_key::
+     *   The per-session private key, an OpenSSL::BN.
      *
      * === Example of a key exchange
      *  dh1 = OpenSSL::PKey::DH.new(2048)
diff --git a/ext/openssl/ossl_pkey_dsa.c b/ext/openssl/ossl_pkey_dsa.c
index 1ddc0d48..7c08620c 100644
--- a/ext/openssl/ossl_pkey_dsa.c
+++ b/ext/openssl/ossl_pkey_dsa.c
@@ -602,8 +602,9 @@ void
 Init_ossl_dsa(void)
 {
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL and mPKey */
     mPKey = rb_define_module_under(mOSSL, "PKey");
+    cPKey = rb_define_class_under(mPKey, "PKey", rb_cObject);
+    ePKeyError = rb_define_class_under(mPKey, "PKeyError", eOSSLError);
 #endif
 
     /* Document-class: OpenSSL::PKey::DSAError
diff --git a/ext/openssl/ossl_pkey_ec.c b/ext/openssl/ossl_pkey_ec.c
index 43eebd26..c3be042a 100644
--- a/ext/openssl/ossl_pkey_ec.c
+++ b/ext/openssl/ossl_pkey_ec.c
@@ -599,12 +599,10 @@ static VALUE ossl_ec_key_to_string(VALUE self, VALUE ciph, VALUE pass, int forma
  *     key.export([cipher, pass_phrase]) => String
  *     key.to_pem([cipher, pass_phrase]) => String
  *
- * Outputs the EC key in PEM encoding.  If +cipher+ and +pass_phrase+ are
- * given they will be used to encrypt the key.  +cipher+ must be an
- * OpenSSL::Cipher::Cipher instance. Note that encryption will only be
- * effective for a private key, public keys will always be encoded in plain
- * text.
- *
+ * Outputs the EC key in PEM encoding.  If +cipher+ and +pass_phrase+ are given
+ * they will be used to encrypt the key.  +cipher+ must be an OpenSSL::Cipher
+ * instance. Note that encryption will only be effective for a private key,
+ * public keys will always be encoded in plain text.
  */
 static VALUE ossl_ec_key_export(int argc, VALUE *argv, VALUE self)
 {
@@ -1694,9 +1692,11 @@ static VALUE ossl_ec_point_mul(int argc, VALUE *argv, VALUE self)
 
 void Init_ossl_ec(void)
 {
-#ifdef DONT_NEED_RDOC_WORKAROUND
-    mOSSL = rb_define_module("OpenSSL");
+#if 0
     mPKey = rb_define_module_under(mOSSL, "PKey");
+    cPKey = rb_define_class_under(mPKey, "PKey", rb_cObject);
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+    ePKeyError = rb_define_class_under(mPKey, "PKeyError", eOSSLError);
 #endif
 
     eECError = rb_define_class_under(mPKey, "ECError", ePKeyError);
diff --git a/ext/openssl/ossl_pkey_rsa.c b/ext/openssl/ossl_pkey_rsa.c
index f1b4f04c..18507ebb 100644
--- a/ext/openssl/ossl_pkey_rsa.c
+++ b/ext/openssl/ossl_pkey_rsa.c
@@ -335,7 +335,7 @@ ossl_rsa_is_private(VALUE self)
  *
  * Outputs this keypair in PEM encoding.  If +cipher+ and +pass_phrase+ are
  * given they will be used to encrypt the key.  +cipher+ must be an
- * OpenSSL::Cipher::Cipher instance.
+ * OpenSSL::Cipher instance.
  */
 static VALUE
 ossl_rsa_export(int argc, VALUE *argv, VALUE self)
@@ -669,8 +669,9 @@ void
 Init_ossl_rsa(void)
 {
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL and mPKey */
     mPKey = rb_define_module_under(mOSSL, "PKey");
+    cPKey = rb_define_class_under(mPKey, "PKey", rb_cObject);
+    ePKeyError = rb_define_class_under(mPKey, "PKeyError", eOSSLError);
 #endif
 
     /* Document-class: OpenSSL::PKey::RSAError
diff --git a/ext/openssl/ossl_rand.c b/ext/openssl/ossl_rand.c
index ff07a41b..ec983624 100644
--- a/ext/openssl/ossl_rand.c
+++ b/ext/openssl/ossl_rand.c
@@ -214,7 +214,8 @@ void
 Init_ossl_rand(void)
 {
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
 #endif
 
     mRandom = rb_define_module_under(mOSSL, "Random");
diff --git a/ext/openssl/ossl_ssl.c b/ext/openssl/ossl_ssl.c
index 58769461..5044c6d1 100644
--- a/ext/openssl/ossl_ssl.c
+++ b/ext/openssl/ossl_ssl.c
@@ -2164,7 +2164,10 @@ Init_ossl_ssl(void)
     VALUE ary;
 
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+    rb_mWaitReadable = rb_define_module_under(rb_cIO, "WaitReadable");
+    rb_mWaitWritable = rb_define_module_under(rb_cIO, "WaitWritable");
 #endif
 
     ID_callback_state = rb_intern("@callback_state");
diff --git a/ext/openssl/ossl_ssl_session.c b/ext/openssl/ossl_ssl_session.c
index 4836891d..81d5c4e4 100644
--- a/ext/openssl/ossl_ssl_session.c
+++ b/ext/openssl/ossl_ssl_session.c
@@ -308,8 +308,9 @@ static VALUE ossl_ssl_session_to_text(VALUE self)
 void Init_ossl_ssl_session(void)
 {
 #if 0
-	mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
-	mSSL = rb_define_module_under(mOSSL, "SSL");
+    mOSSL = rb_define_module("OpenSSL");
+    mSSL = rb_define_module_under(mOSSL, "SSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
 #endif
 	cSSLSession = rb_define_class_under(mSSL, "Session", rb_cObject);
 	eSSLSession = rb_define_class_under(cSSLSession, "SessionError", eOSSLError);
diff --git a/ext/openssl/ossl_x509.c b/ext/openssl/ossl_x509.c
index 14f794e8..027bf7a5 100644
--- a/ext/openssl/ossl_x509.c
+++ b/ext/openssl/ossl_x509.c
@@ -34,6 +34,10 @@ ossl_x509_time_adjust(ASN1_TIME *s, VALUE time)
 void
 Init_ossl_x509(void)
 {
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+#endif
+
     mX509 = rb_define_module_under(mOSSL, "X509");
 
     Init_ossl_x509attr();
diff --git a/ext/openssl/ossl_x509attr.c b/ext/openssl/ossl_x509attr.c
index 78ce236d..fc1690ce 100644
--- a/ext/openssl/ossl_x509attr.c
+++ b/ext/openssl/ossl_x509attr.c
@@ -289,6 +289,12 @@ ossl_x509attr_to_der(VALUE self)
 void
 Init_ossl_x509attr(void)
 {
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+    mX509 = rb_define_module_under(mOSSL, "X509");
+#endif
+
     eX509AttrError = rb_define_class_under(mX509, "AttributeError", eOSSLError);
 
     cX509Attr = rb_define_class_under(mX509, "Attribute", rb_cObject);
diff --git a/ext/openssl/ossl_x509cert.c b/ext/openssl/ossl_x509cert.c
index a7e37960..f8a1618a 100644
--- a/ext/openssl/ossl_x509cert.c
+++ b/ext/openssl/ossl_x509cert.c
@@ -720,9 +720,9 @@ ossl_x509_inspect(VALUE self)
 void
 Init_ossl_x509cert(void)
 {
-
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
     mX509 = rb_define_module_under(mOSSL, "X509");
 #endif
 
diff --git a/ext/openssl/ossl_x509crl.c b/ext/openssl/ossl_x509crl.c
index 2cbe4f94..4f656237 100644
--- a/ext/openssl/ossl_x509crl.c
+++ b/ext/openssl/ossl_x509crl.c
@@ -526,6 +526,12 @@ ossl_x509crl_add_extension(VALUE self, VALUE extension)
 void
 Init_ossl_x509crl(void)
 {
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+    mX509 = rb_define_module_under(mOSSL, "X509");
+#endif
+
     eX509CRLError = rb_define_class_under(mX509, "CRLError", eOSSLError);
 
     cX509CRL = rb_define_class_under(mX509, "CRL", rb_cObject);
diff --git a/ext/openssl/ossl_x509ext.c b/ext/openssl/ossl_x509ext.c
index e5817543..48daa6bb 100644
--- a/ext/openssl/ossl_x509ext.c
+++ b/ext/openssl/ossl_x509ext.c
@@ -225,12 +225,11 @@ ossl_x509extfactory_initialize(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * Array to X509_EXTENSION
- * Structure:
- * ["ln", "value", bool_critical] or
- * ["sn", "value", bool_critical] or
- * ["ln", "critical,value"] or the same for sn
- * ["ln", "value"] => not critical
+ * call-seq:
+ *   ef.create_ext(ln_or_sn, "value", critical = false) -> X509::Extension
+ *   ef.create_ext(ln_or_sn, "critical,value")          -> X509::Extension
+ *
+ * Creates a new X509::Extension with passed values. See also x509v3_config(5).
  */
 static VALUE
 ossl_x509extfactory_create_ext(int argc, VALUE *argv, VALUE self)
@@ -447,6 +446,12 @@ ossl_x509ext_to_der(VALUE obj)
 void
 Init_ossl_x509ext(void)
 {
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+    mX509 = rb_define_module_under(mOSSL, "X509");
+#endif
+
     eX509ExtError = rb_define_class_under(mX509, "ExtensionError", eOSSLError);
 
     cX509ExtFactory = rb_define_class_under(mX509, "ExtensionFactory", rb_cObject);
diff --git a/ext/openssl/ossl_x509name.c b/ext/openssl/ossl_x509name.c
index ff307c06..a99be7ee 100644
--- a/ext/openssl/ossl_x509name.c
+++ b/ext/openssl/ossl_x509name.c
@@ -450,6 +450,12 @@ Init_ossl_x509name(void)
 {
     VALUE utf8str, ptrstr, ia5str, hash;
 
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+    mX509 = rb_define_module_under(mOSSL, "X509");
+#endif
+
     id_aref = rb_intern("[]");
     eX509NameError = rb_define_class_under(mX509, "NameError", eOSSLError);
     cX509Name = rb_define_class_under(mX509, "Name", rb_cObject);
@@ -474,8 +480,7 @@ Init_ossl_x509name(void)
     ptrstr = INT2NUM(V_ASN1_PRINTABLESTRING);
     ia5str = INT2NUM(V_ASN1_IA5STRING);
 
-    /* Document-const: DEFAULT_OBJECT_TYPE
-     *
+    /*
      * The default object type for name entries.
      */
     rb_define_const(cX509Name, "DEFAULT_OBJECT_TYPE", utf8str);
@@ -489,14 +494,12 @@ Init_ossl_x509name(void)
     rb_hash_aset(hash, rb_str_new2("domainComponent"), ia5str);
     rb_hash_aset(hash, rb_str_new2("emailAddress"), ia5str);
 
-    /* Document-const: OBJECT_TYPE_TEMPLATE
-     *
+    /*
      * The default object type template for name entries.
      */
     rb_define_const(cX509Name, "OBJECT_TYPE_TEMPLATE", hash);
 
-    /* Document-const: COMPAT
-     *
+    /*
      * A flag for #to_s.
      *
      * Breaks the name returned into multiple lines if longer than 80
@@ -504,24 +507,21 @@ Init_ossl_x509name(void)
      */
     rb_define_const(cX509Name, "COMPAT", ULONG2NUM(XN_FLAG_COMPAT));
 
-    /* Document-const: RFC2253
-     *
+    /*
      * A flag for #to_s.
      *
      * Returns an RFC2253 format name.
      */
     rb_define_const(cX509Name, "RFC2253", ULONG2NUM(XN_FLAG_RFC2253));
 
-    /* Document-const: ONELINE
-     *
+    /*
      * A flag for #to_s.
      *
      * Returns a more readable format than RFC2253.
      */
     rb_define_const(cX509Name, "ONELINE", ULONG2NUM(XN_FLAG_ONELINE));
 
-    /* Document-const: MULTILINE
-     *
+    /*
      * A flag for #to_s.
      *
      * Returns a multiline format.
diff --git a/ext/openssl/ossl_x509req.c b/ext/openssl/ossl_x509req.c
index 9025d4fe..2ca9c809 100644
--- a/ext/openssl/ossl_x509req.c
+++ b/ext/openssl/ossl_x509req.c
@@ -459,6 +459,12 @@ ossl_x509req_add_attribute(VALUE self, VALUE attr)
 void
 Init_ossl_x509req(void)
 {
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+    mX509 = rb_define_module_under(mOSSL, "X509");
+#endif
+
     eX509ReqError = rb_define_class_under(mX509, "RequestError", eOSSLError);
 
     cX509Req = rb_define_class_under(mX509, "Request", rb_cObject);
diff --git a/ext/openssl/ossl_x509revoked.c b/ext/openssl/ossl_x509revoked.c
index 067bec8c..87a9b323 100644
--- a/ext/openssl/ossl_x509revoked.c
+++ b/ext/openssl/ossl_x509revoked.c
@@ -227,6 +227,12 @@ ossl_x509revoked_add_extension(VALUE self, VALUE ext)
 void
 Init_ossl_x509revoked(void)
 {
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+    mX509 = rb_define_module_under(mOSSL, "X509");
+#endif
+
     eX509RevError = rb_define_class_under(mX509, "RevokedError", eOSSLError);
 
     cX509Rev = rb_define_class_under(mX509, "Revoked", rb_cObject);
diff --git a/ext/openssl/ossl_x509store.c b/ext/openssl/ossl_x509store.c
index 26426d18..f3d6bf3b 100644
--- a/ext/openssl/ossl_x509store.c
+++ b/ext/openssl/ossl_x509store.c
@@ -613,7 +613,8 @@ Init_ossl_x509store(void)
     VALUE x509stctx;
 
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
     mX509 = rb_define_module_under(mOSSL, "X509");
 #endif