[DOC] Backport ruby/openssl@86eb721 [ci skip]

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

ext/openssl/ossl_asn1.c

@@ -1360,13 +1360,13 @@ ossl_asn1cons_each(VALUE self)
 
 /*
  * call-seq:
- *    ObjectId.register(object_id, short_name, long_name)
+ *    OpenSSL::ASN1::ObjectId.register(object_id, short_name, long_name)
  *
  * This adds a new ObjectId to the internal tables. Where +object_id+ is the
  * numerical form, +short_name+ is the short name, and +long_name+ is the long
  * name.
  *
- * Returns +true+ if successful. Raises an ASN1Error otherwise.
+ * Returns +true+ if successful. Raises an OpenSSL::ASN1::ASN1Error if it fails.
  *
  */
 static VALUE
@@ -1384,11 +1384,11 @@ ossl_asn1obj_s_register(VALUE self, VALUE oid, VALUE sn, VALUE ln)
 
 /* Document-method: OpenSSL::ASN1::ObjectId#sn
  *
- * The short name of the ObjectId, as defined in +openssl/objects.h+.
+ * The short name of the ObjectId, as defined in <openssl/objects.h>.
  */
 /* Document-method: OpenSSL::ASN1::ObjectId#short_name
  *
- * #short_name is an alias to #sn
+ * +short_name+ is an alias to +sn+
  */
 static VALUE
 ossl_asn1obj_get_sn(VALUE self)
@@ -1405,11 +1405,11 @@ ossl_asn1obj_get_sn(VALUE self)
 
 /* Document-method: OpenSSL::ASN1::ObjectId#ln
  *
- * The long name of the ObjectId, as defined in +openssl/objects.h+.
+ * The long name of the ObjectId, as defined in <openssl/objects.h>.
  */
-/* Document-method: OpenSSL::ASN1::ObjectId.long_name
+/* Document-method: OpenSSL::ASN1::ObjectId#long_name
  *
- * #long_name is an alias to #ln
+ * +long_name+ is an alias to +ln+
  */
 static VALUE
 ossl_asn1obj_get_ln(VALUE self)
@@ -1424,9 +1424,9 @@ ossl_asn1obj_get_ln(VALUE self)
     return ret;
 }
 
-/* Document-method: OpenSSL::ASN1::ObjectId#oid
+/* Document-method: OpenSSL::ASN1::ObjectId.oid
  *
- * The object identifier as a String.
+ * The object identifier as a +String+, e.g. "1.2.3.4.5"
  */
 static VALUE
 ossl_asn1obj_get_oid(VALUE self)
@@ -1809,6 +1809,10 @@ Init_ossl_asn1(void)
      *
      * == OpenSSL::ASN1::ObjectId
      *
+     * NOTE: While OpenSSL::ASN1::ObjectId.new will allocate a new ObjectId,
+     * it is not typically allocated this way, but rather that are recieved 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.

ext/openssl/ossl_bn.c

@@ -53,6 +53,13 @@ static const rb_data_type_t ossl_bn_type = {
  * Classes
  */
 VALUE cBN;
+
+/* Document-class: OpenSSL::BNError
+ *
+ * BNError < OpenSSLError
+ *
+ * Generic Error for all of OpenSSL::BN (big num)
+ */
 VALUE eBNError;
 
 /*
@@ -121,13 +128,15 @@ ossl_bn_alloc(VALUE klass)
     return obj;
 }
 
-/*
+/* Document-method: OpenSSL::BN.new
- * call-seq:
+ *
- *    BN.new => aBN
+ *    OpenSSL::BN.new => aBN
- *    BN.new(bn) => aBN
+ *    OpenSSL::BN.new(bn) => aBN
- *    BN.new(integer) => aBN
+ *    OpenSSL::BN.new(integer) => aBN
- *    BN.new(string) => aBN
+ *    OpenSSL::BN.new(string) => aBN
- *    BN.new(string, 0 | 2 | 10 | 16) => aBN
+ *    OpenSSL::BN.new(string, 0 | 2 | 10 | 16) => aBN
+ *
+ * Construct a new OpenSSL BigNum object.
  */
 static VALUE
 ossl_bn_initialize(int argc, VALUE *argv, VALUE self)
@@ -322,7 +331,7 @@ ossl_bn_coerce(VALUE self, VALUE other)
 #define BIGNUM_BOOL1(func)				\
     /*							\
      * call-seq:					\
-     *   bn.##func -> true | false			\
+     *   bn.##func => true | false			\
      *							\
      */							\
     static VALUE					\
@@ -342,7 +351,7 @@ BIGNUM_BOOL1(is_odd)
 #define BIGNUM_1c(func)					\
     /*							\
      * call-seq:					\
-     *   bn.##func -> aBN				\
+     *   bn.##func => aBN				\
      *							\
      */							\
     static VALUE					\
@@ -366,7 +375,7 @@ BIGNUM_1c(sqr)
 #define BIGNUM_2(func)					\
     /*							\
      * call-seq:					\
-     *   bn.##func(bn2) -> aBN				\
+     *   bn.##func(bn2) => aBN				\
      *							\
      */							\
     static VALUE					\
@@ -391,7 +400,7 @@ BIGNUM_2(sub)
 #define BIGNUM_2c(func)						\
     /*								\
      * call-seq:						\
-     *   bn.##func(bn2) -> aBN					\
+     *   bn.##func(bn2) => aBN					\
      *								\
      */								\
     static VALUE						\
@@ -420,6 +429,8 @@ BIGNUM_2c(mod_inverse)
 /*
  * call-seq:
  *    bn1 / bn2 => [result, remainder]
+ *
+ * Division of OpenSSL::BN instances
  */
 static VALUE
 ossl_bn_div(VALUE self, VALUE other)
@@ -495,9 +506,13 @@ BIGNUM_BIT(set_bit)
 BIGNUM_BIT(clear_bit)
 BIGNUM_BIT(mask_bits)
 
-/*
+/* Document-method: OpenSSL::BN#bit_set?
- * call-seq:
+ *
+ * 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)
@@ -661,7 +676,7 @@ ossl_bn_s_generate_prime(int argc, VALUE *argv, VALUE klass)
 #define BIGNUM_NUM(func)			\
     /*							\
      * call-seq:					\
-     *   bn.##func -> integer				\
+     *   bn.##func => integer				\
      *							\
      */							\
     static VALUE 				\
@@ -695,7 +710,7 @@ ossl_bn_copy(VALUE self, VALUE other)
 #define BIGNUM_CMP(func)				\
     /*							\
      * call-seq:					\
-     *   bn.##func(bn2) -> integer			\
+     *   bn.##func(bn2) => integer			\
      *							\
      */							\
     static VALUE					\
@@ -708,6 +723,13 @@ ossl_bn_copy(VALUE self, VALUE other)
 BIGNUM_CMP(cmp)
 BIGNUM_CMP(ucmp)
 
+/*
+ *  call-seq:
+ *     big.eql?(obj) => true or false
+ *
+ *  Returns <code>true</code> only if <i>obj</i> is a
+ *  <code>Bignum</code> with the same value as <i>big</i>. Contrast this
+ */
 static VALUE
 ossl_bn_eql(VALUE self, VALUE other)
 {