[ruby/openssl] bn: update documentation of OpenSSL::BN#initialize and #to_s

Clarify that BN.new(str, 2) and bn.to_s(2) handles binary string in
big-endian, and the sign of the bignum is ignored.

Reference: https://github.com/ruby/openssl/issues/431

https://github.com/ruby/openssl/commit/6fae2bd612

1 files changed, 36 insertions, 14 deletions

diff --git a/ext/openssl/ossl_bn.c b/ext/openssl/ossl_bn.c
index ac3f838221..025307894f 100644
--- a/ext/openssl/ossl_bn.c
+++ b/ext/openssl/ossl_bn.c
@@ -223,12 +223,29 @@ ossl_bn_alloc(VALUE klass)
 
 /*
  * call-seq:
- *    OpenSSL::BN.new(bn) => aBN
- *    OpenSSL::BN.new(integer) => aBN
- *    OpenSSL::BN.new(string) => aBN
- *    OpenSSL::BN.new(string, 0 | 2 | 10 | 16) => aBN
+ *    OpenSSL::BN.new(bn) -> aBN
+ *    OpenSSL::BN.new(integer) -> aBN
+ *    OpenSSL::BN.new(string, base = 10) -> aBN
  *
- * Construct a new OpenSSL BIGNUM object.
+ * Construct a new \OpenSSL BIGNUM object.
+ *
+ * If +bn+ is an Integer or OpenSSL::BN, a new instance of OpenSSL::BN
+ * representing the same value is returned. See also Integer#to_bn for the
+ * short-hand.
+ *
+ * If a String is given, the content will be parsed according to +base+.
+ *
+ * +string+::
+ *   The string to be parsed.
+ * +base+::
+ *   The format. Must be one of the following:
+ *   - +0+  - MPI format. See the man page BN_mpi2bn(3) for details.
+ *   - +2+  - Variable-length and big-endian binary encoding of a positive
+ *     number.
+ *   - +10+ - Decimal number representation, with a leading '-' for a negative
+ *     number.
+ *   - +16+ - Hexadeciaml number representation, with a leading '-' for a
+ *     negative number.
  */
 static VALUE
 ossl_bn_initialize(int argc, VALUE *argv, VALUE self)
@@ -296,16 +313,21 @@ ossl_bn_initialize(int argc, VALUE *argv, VALUE self)
 
 /*
  * call-seq:
- *    bn.to_s => string
- *    bn.to_s(base) => string
+ *    bn.to_s(base = 10) -> string
  *
- * === Parameters
- * * _base_ - Integer
- *   Valid values:
- *   * 0 - MPI
- *   * 2 - binary
- *   * 10 - the default
- *   * 16 - hex
+ * Returns the string representation of the bignum.
+ *
+ * BN.new can parse the encoded string to convert back into an OpenSSL::BN.
+ *
+ * +base+::
+ *   The format. Must be one of the following:
+ *   - +0+  - MPI format. See the man page BN_bn2mpi(3) for details.
+ *   - +2+  - Variable-length and big-endian binary encoding. The sign of
+ *     the bignum is ignored.
+ *   - +10+ - Decimal number representation, with a leading '-' for a negative
+ *     bignum.
+ *   - +16+ - Hexadeciaml number representation, with a leading '-' for a
+ *     negative bignum.
  */
 static VALUE
 ossl_bn_to_s(int argc, VALUE *argv, VALUE self)