Fix RDoc markuptopic/fix-rdoc-markup

Ruby core uses _str_ for emphasizing argument names and +str+ for codes.
Match with the rule for better rendering.

26 files changed, 427 insertions, 417 deletions

diff --git a/ext/openssl/ossl.c b/ext/openssl/ossl.c
index bcadc3e1..0cc88c7b 100644
--- a/ext/openssl/ossl.c
+++ b/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
  *
diff --git a/ext/openssl/ossl_asn1.c b/ext/openssl/ossl_asn1.c
index 9b554820..d2914821 100644
--- a/ext/openssl/ossl_asn1.c
+++ b/ext/openssl/ossl_asn1.c
@@ -645,12 +645,12 @@ ossl_asn1_class2sym(int tc)
  * call-seq:
  *    OpenSSL::ASN1::ASN1Data.new(value, tag, tag_class) => ASN1Data
  *
- * +value+: Please have a look at Constructive and Primitive to see how Ruby
+ * _value_: Please have a look at Constructive and Primitive to see how Ruby
  * types are mapped to ASN.1 types and vice versa.
  *
- * +tag+: A +Number+ indicating the tag number.
+ * _tag_: An Integer indicating the tag number.
  *
- * +tag_class+: A +Symbol+ indicating the tag class. Please cf. ASN1 for
+ * _tag_class_: A Symbol indicating the tag class. Please cf. ASN1 for
  * possible values.
  *
  * == Example
@@ -950,13 +950,13 @@ int_ossl_decode_sanity_check(long len, long read, long offset)
  *
  * If a block is given, it prints out each of the elements encountered.
  * Block parameters are (in that order):
- * * depth: The recursion depth, plus one with each constructed value being encountered (Number)
- * * offset: Current byte offset (Number)
- * * header length: Combined length in bytes of the Tag and Length headers. (Number)
- * * length: The overall remaining length of the entire data (Number)
+ * * depth: The recursion depth, plus one with each constructed value being encountered (Integer)
+ * * offset: Current byte offset (Integer)
+ * * header length: Combined length in bytes of the Tag and Length headers. (Integer)
+ * * length: The overall remaining length of the entire data (Integer)
  * * constructed: Whether this value is constructed or not (Boolean)
  * * tag_class: Current tag class (Symbol)
- * * tag: The current tag (Number)
+ * * tag: The current tag number (Integer)
  *
  * == Example
  *   der = File.binread('asn1data.der')
@@ -986,9 +986,9 @@ ossl_asn1_traverse(VALUE self, VALUE obj)
  * call-seq:
  *    OpenSSL::ASN1.decode(der) -> ASN1Data
  *
- * Decodes a BER- or DER-encoded value and creates an ASN1Data instance. +der+
- * may be a +String+ or any object that features a +#to_der+ method transforming
- * it into a BER-/DER-encoded +String+.
+ * Decodes a BER- or DER-encoded value and creates an ASN1Data instance. _der_
+ * may be a String or any object that features a +.to_der+ method transforming
+ * it into a BER-/DER-encoded String+
  *
  * == Example
  *   der = File.binread('asn1data')
@@ -1016,9 +1016,9 @@ ossl_asn1_decode(VALUE self, VALUE obj)
  * call-seq:
  *    OpenSSL::ASN1.decode_all(der) -> Array of ASN1Data
  *
- * Similar to +decode+ with the difference that +decode+ expects one
- * distinct value represented in +der+. +decode_all+ on the contrary
- * decodes a sequence of sequential BER/DER values lined up in +der+
+ * Similar to #decode with the difference that #decode expects one
+ * distinct value represented in _der_. #decode_all on the contrary
+ * decodes a sequence of sequential BER/DER values lined up in _der_
  * and returns them as an array.
  *
  * == Example
@@ -1053,19 +1053,19 @@ ossl_asn1_decode_all(VALUE self, VALUE obj)
 
 /*
  * call-seq:
- *    OpenSSL::ASN1::Primitive.new( value [, tag, tagging, tag_class ]) => Primitive
+ *    OpenSSL::ASN1::Primitive.new(value [, tag, tagging, tag_class ]) => Primitive
  *
- * +value+: is mandatory.
+ * _value_: is mandatory.
  *
- * +tag+: optional, may be specified for tagged values. If no +tag+ is
+ * _tag_: optional, may be specified for tagged values. If no _tag_ is
  * specified, the UNIVERSAL tag corresponding to the Primitive sub-class
  * is used by default.
  *
- * +tagging+: may be used as an encoding hint to encode a value either
+ * _tagging_: may be used as an encoding hint to encode a value either
  * explicitly or implicitly, see ASN1 for possible values.
  *
- * +tag_class+: if +tag+ and +tagging+ are +nil+ then this is set to
- * +:UNIVERSAL+ by default. If either +tag+ or +tagging+ are set then
+ * _tag_class_: if _tag_ and _tagging_ are +nil+ then this is set to
+ * +:UNIVERSAL+ by default. If either _tag_ or _tagging_ are set then
  * +:CONTEXT_SPECIFIC+ is used as the default. For possible values please
  * cf. ASN1.
  *
@@ -1129,7 +1129,7 @@ ossl_asn1eoc_initialize(VALUE self) {
  * call-seq:
  *    asn1.to_der => DER-encoded String
  *
- * See ASN1Data#to_der for details. *
+ * See ASN1Data#to_der for details.
  */
 static VALUE
 ossl_asn1prim_to_der(VALUE self)
@@ -1261,8 +1261,8 @@ ossl_asn1cons_to_der(VALUE self)
  * call-seq:
  *    asn1_ary.each { |asn1| block } => asn1_ary
  *
- * Calls <i>block</i> once for each element in +self+, passing that element
- * as parameter +asn1+. If no block is given, an enumerator is returned
+ * Calls the given block once for each element in self, passing that element
+ * as parameter _asn1_. If no block is given, an enumerator is returned
  * instead.
  *
  * == Example
@@ -1282,8 +1282,8 @@ ossl_asn1cons_each(VALUE self)
  * call-seq:
  *    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
+ * 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 OpenSSL::ASN1::ASN1Error if it fails.
@@ -1302,14 +1302,13 @@ ossl_asn1obj_s_register(VALUE self, VALUE oid, VALUE sn, VALUE ln)
     return Qtrue;
 }
 
-/* Document-method: OpenSSL::ASN1::ObjectId#sn
+/*
+ * call-seq:
+ *    oid.sn -> string
+ *    oid.short_name -> string
  *
  * 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+
- */
 static VALUE
 ossl_asn1obj_get_sn(VALUE self)
 {
@@ -1323,14 +1322,13 @@ ossl_asn1obj_get_sn(VALUE self)
     return ret;
 }
 
-/* Document-method: OpenSSL::ASN1::ObjectId#ln
+/*
+ * call-seq:
+ *    oid.ln -> string
+ *    oid.long_name -> string
  *
  * The long name of the ObjectId, as defined in <openssl/objects.h>.
  */
-/* Document-method: OpenSSL::ASN1::ObjectId#long_name
- *
- * +long_name+ is an alias to +ln+
- */
 static VALUE
 ossl_asn1obj_get_ln(VALUE self)
 {
@@ -1344,9 +1342,12 @@ ossl_asn1obj_get_ln(VALUE self)
     return ret;
 }
 
-/* Document-method: OpenSSL::ASN1::ObjectId#oid
+/*
+ * call-seq:
+ *    oid.oid -> string
  *
- * The object identifier as a +String+, e.g. "1.2.3.4.5"
+ * Returns a String representing the Object Identifier in the dot notation,
+ * e.g. "1.2.3.4.5"
  */
 static VALUE
 ossl_asn1obj_get_oid(VALUE self)
@@ -1439,13 +1440,13 @@ Init_ossl_asn1(void)
      * == ASN.1 class hierarchy
      *
      * The base class representing ASN.1 structures is ASN1Data. ASN1Data offers
-     * attributes to read and set the +tag+, the +tag_class+ and finally the
-     * +value+ of a particular ASN.1 item. Upon parsing, any tagged values
+     * attributes to read and set the _tag_, the _tag_class_ and finally the
+     * _value_ of a particular ASN.1 item. Upon parsing, any tagged values
      * (implicit or explicit) will be represented by ASN1Data instances because
      * their "real type" can only be determined using out-of-band information
      * from the ASN.1 type declaration. Since this information is normally
      * known when encoding a type, all sub-classes of ASN1Data offer an
-     * additional attribute +tagging+ that allows to encode a value implicitly
+     * additional attribute _tagging_ that allows to encode a value implicitly
      * (+:IMPLICIT+) or explicitly (+:EXPLICIT+).
      *
      * === Constructive
@@ -1473,18 +1474,18 @@ Init_ossl_asn1(void)
      * Please cf. Primitive documentation for details on sub-classes and
      * their respective mappings of ASN.1 data types to Ruby objects.
      *
-     * == Possible values for +tagging+
+     * == Possible values for _tagging_
      *
      * When constructing an ASN1Data object the ASN.1 type definition may
      * require certain elements to be either implicitly or explicitly tagged.
-     * This can be achieved by setting the +tagging+ attribute manually for
+     * This can be achieved by setting the _tagging_ attribute manually for
      * sub-classes of ASN1Data. Use the symbol +:IMPLICIT+ for implicit
      * tagging and +:EXPLICIT+ if the element requires explicit tagging.
      *
-     * == Possible values for +tag_class+
+     * == Possible values for _tag_class_
      *
      * It is possible to create arbitrary ASN1Data objects that also support
-     * a PRIVATE or APPLICATION tag class. Possible values for the +tag_class+
+     * a PRIVATE or APPLICATION tag class. Possible values for the _tag_class_
      * attribute are:
      * * +:UNIVERSAL+ (the default for untagged values)
      * * +:CONTEXT_SPECIFIC+ (the default for tagged values)
@@ -1586,9 +1587,9 @@ Init_ossl_asn1(void)
      *
      * An implicitly 1-tagged INTEGER value will be parsed as an
      * ASN1Data with
-     * * +tag+ equal to 1
-     * * +tag_class+ equal to +:CONTEXT_SPECIFIC+
-     * * +value+ equal to a +String+ that carries the raw encoding
+     * * _tag_ equal to 1
+     * * _tag_class_ equal to +:CONTEXT_SPECIFIC+
+     * * _value_ equal to a String that carries the raw encoding
      *   of the INTEGER.
      * This implies that a subsequent decoding step is required to
      * completely decode implicitly tagged values.
@@ -1597,9 +1598,9 @@ Init_ossl_asn1(void)
      *
      * An explicitly 1-tagged INTEGER value will be parsed as an
      * ASN1Data with
-     * * +tag+ equal to 1
-     * * +tag_class+ equal to +:CONTEXT_SPECIFIC+
-     * * +value+ equal to an +Array+ with one single element, an
+     * * _tag_ equal to 1
+     * * _tag_class_ equal to +:CONTEXT_SPECIFIC+
+     * * _value_ equal to an Array with one single element, an
      *   instance of OpenSSL::ASN1::Integer, i.e. the inner element
      *   is the non-tagged primitive value, and the tagging is represented
      *   in the outer ASN1Data
@@ -1660,16 +1661,16 @@ Init_ossl_asn1(void)
      */
     rb_attr(cASN1Data, rb_intern("value"), 1, 1, 0);
     /*
-     * A +Number+ representing the tag number of this ASN1Data. Never +nil+.
+     * An Integer representing the tag number of this ASN1Data. Never +nil+.
      */
     rb_attr(cASN1Data, rb_intern("tag"), 1, 1, 0);
     /*
-     * A +Symbol+ representing the tag class of this ASN1Data. Never +nil+.
+     * A Symbol representing the tag class of this ASN1Data. Never +nil+.
      * See ASN1Data for possible values.
      */
     rb_attr(cASN1Data, rb_intern("tag_class"), 1, 1, 0);
     /*
-     * Never +nil+. A +Boolean+ indicating whether the encoding was infinite
+     * Never +nil+. A boolean value indicating whether the encoding was infinite
      * length (in the case of parsing) or whether an infinite length encoding
      * shall be used (in the encoding case).
      * In DER, every value has a finite length associated with it. But in
@@ -1692,41 +1693,41 @@ Init_ossl_asn1(void)
     /* Document-class: OpenSSL::ASN1::Primitive
      *
      * The parent class for all primitive encodings. Attributes are the same as
-     * for ASN1Data, with the addition of +tagging+.
+     * for ASN1Data, with the addition of _tagging_
      * Primitive values can never be infinite length encodings, thus it is not
-     * possible to set the +infinite_length+ attribute for Primitive and its
+     * possible to set the _infinite_length_ attribute for Primitive and its
      * sub-classes.
      *
      * == Primitive sub-classes and their mapping to Ruby classes
-     * * OpenSSL::ASN1::EndOfContent    <=> +value+ is always +nil+
-     * * OpenSSL::ASN1::Boolean         <=> +value+ is a +Boolean+
-     * * OpenSSL::ASN1::Integer         <=> +value+ is a +Number+
-     * * OpenSSL::ASN1::BitString       <=> +value+ is a +String+
-     * * OpenSSL::ASN1::OctetString     <=> +value+ is a +String+
-     * * OpenSSL::ASN1::Null            <=> +value+ is always +nil+
-     * * OpenSSL::ASN1::Object          <=> +value+ is a +String+
-     * * OpenSSL::ASN1::Enumerated      <=> +value+ is a +Number+
-     * * OpenSSL::ASN1::UTF8String      <=> +value+ is a +String+
-     * * OpenSSL::ASN1::NumericString   <=> +value+ is a +String+
-     * * OpenSSL::ASN1::PrintableString <=> +value+ is a +String+
-     * * OpenSSL::ASN1::T61String       <=> +value+ is a +String+
-     * * OpenSSL::ASN1::VideotexString  <=> +value+ is a +String+
-     * * OpenSSL::ASN1::IA5String       <=> +value+ is a +String+
-     * * OpenSSL::ASN1::UTCTime         <=> +value+ is a +Time+
-     * * OpenSSL::ASN1::GeneralizedTime <=> +value+ is a +Time+
-     * * OpenSSL::ASN1::GraphicString   <=> +value+ is a +String+
-     * * OpenSSL::ASN1::ISO64String     <=> +value+ is a +String+
-     * * OpenSSL::ASN1::GeneralString   <=> +value+ is a +String+
-     * * OpenSSL::ASN1::UniversalString <=> +value+ is a +String+
-     * * OpenSSL::ASN1::BMPString       <=> +value+ is a +String+
+     * * OpenSSL::ASN1::EndOfContent    <=> _value_ is always +nil+
+     * * OpenSSL::ASN1::Boolean         <=> _value_ is +true+ or +false+
+     * * OpenSSL::ASN1::Integer         <=> _value_ is an Integer
+     * * OpenSSL::ASN1::BitString       <=> _value_ is a String
+     * * OpenSSL::ASN1::OctetString     <=> _value_ is a String
+     * * OpenSSL::ASN1::Null            <=> _value_ is always +nil+
+     * * OpenSSL::ASN1::Object          <=> _value_ is a String
+     * * OpenSSL::ASN1::Enumerated      <=> _value_ is an Integer
+     * * OpenSSL::ASN1::UTF8String      <=> _value_ is a String
+     * * OpenSSL::ASN1::NumericString   <=> _value_ is a String
+     * * OpenSSL::ASN1::PrintableString <=> _value_ is a String
+     * * OpenSSL::ASN1::T61String       <=> _value_ is a String
+     * * OpenSSL::ASN1::VideotexString  <=> _value_ is a String
+     * * OpenSSL::ASN1::IA5String       <=> _value_ is a String
+     * * OpenSSL::ASN1::UTCTime         <=> _value_ is a Time
+     * * OpenSSL::ASN1::GeneralizedTime <=> _value_ is a Time
+     * * OpenSSL::ASN1::GraphicString   <=> _value_ is a String
+     * * OpenSSL::ASN1::ISO64String     <=> _value_ is a String
+     * * OpenSSL::ASN1::GeneralString   <=> _value_ is a String
+     * * OpenSSL::ASN1::UniversalString <=> _value_ is a String
+     * * OpenSSL::ASN1::BMPString       <=> _value_ is a String
      *
      * == OpenSSL::ASN1::BitString
      *
      * === Additional attributes
-     * +unused_bits+: if the underlying BIT STRING's
-     * length is a multiple of 8 then +unused_bits+ is 0. Otherwise
-     * +unused_bits+ indicates the number of bits that are to be ignored in
-     * the final octet of the +BitString+'s +value+.
+     * _unused_bits_: if the underlying BIT STRING's
+     * length is a multiple of 8 then _unused_bits_ is 0. Otherwise
+     * _unused_bits_ indicates the number of bits that are to be ignored in
+     * the final octet of the BitString's _value_.
      *
      * == OpenSSL::ASN1::ObjectId
      *
@@ -1735,15 +1736,15 @@ Init_ossl_asn1(void)
      * 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>.
-     * * +oid+: the object identifier as a +String+, e.g. "1.2.3.4.5"
-     * * +short_name+: alias for +sn+.
-     * * +long_name+: alias for +ln+.
+     * * _sn_: the short name as defined in <openssl/objects.h>.
+     * * _ln_: the long name as defined in <openssl/objects.h>.
+     * * _oid_: the object identifier as a String, e.g. "1.2.3.4.5"
+     * * _short_name_: alias for _sn_.
+     * * _long_name_: alias for _ln_.
      *
      * == Examples
      * With the Exception of OpenSSL::ASN1::EndOfContent, each Primitive class
-     * constructor takes at least one parameter, the +value+.
+     * constructor takes at least one parameter, the _value_.
      *
      * === Creating EndOfContent
      *   eoc = OpenSSL::ASN1::EndOfContent.new
@@ -1757,7 +1758,7 @@ Init_ossl_asn1(void)
     /*
      * May be used as a hint for encoding a value either implicitly or
      * explicitly by setting it either to +:IMPLICIT+ or to +:EXPLICIT+.
-     * +tagging+ is not set when a ASN.1 structure is parsed using
+     * _tagging_ is not set when a ASN.1 structure is parsed using
      * OpenSSL::ASN1.decode.
      */
     rb_attr(cASN1Primitive, rb_intern("tagging"), 1, 1, Qtrue);
@@ -1767,9 +1768,9 @@ Init_ossl_asn1(void)
 
     /* Document-class: OpenSSL::ASN1::Constructive
      *
-     * The parent class for all constructed encodings. The +value+ attribute
-     * of a Constructive is always an +Array+. Attributes are the same as
-     * for ASN1Data, with the addition of +tagging+.
+     * The parent class for all constructed encodings. The _value_ attribute
+     * of a Constructive is always an Array. Attributes are the same as
+     * for ASN1Data, with the addition of _tagging_.
      *
      * == SET and SEQUENCE
      *
@@ -1796,19 +1797,19 @@ Init_ossl_asn1(void)
      *
      * The only case where Constructive is used directly is for infinite
      * length encodings of primitive values. These encodings are always
-     * constructed, with the contents of the +value+ +Array+ being either
+     * constructed, with the contents of the _value_ Array being either
      * UNIVERSAL non-infinite length partial encodings of the actual value
      * or again constructive encodings with infinite length (i.e. infinite
      * length primitive encodings may be constructed recursively with another
      * infinite length value within an already infinite length value). Each
      * partial encoding must be of the same UNIVERSAL type as the overall
      * encoding. The value of the overall encoding consists of the
-     * concatenation of each partial encoding taken in sequence. The +value+
+     * concatenation of each partial encoding taken in sequence. The _value_
      * array of the outer infinite length value must end with a
      * OpenSSL::ASN1::EndOfContent instance.
      *
      * Please note that it is not possible to encode Constructive without
-     * the +infinite_length+ attribute being set to +true+, use
+     * the _infinite_length_ attribute being set to +true+, use
      * OpenSSL::ASN1::Sequence or OpenSSL::ASN1::Set in these cases instead.
      *
      * === Example - Infinite length OCTET STRING
@@ -1832,7 +1833,7 @@ Init_ossl_asn1(void)
     /*
      * May be used as a hint for encoding a value either implicitly or
      * explicitly by setting it either to +:IMPLICIT+ or to +:EXPLICIT+.
-     * +tagging+ is not set when a ASN.1 structure is parsed using
+     * _tagging_ is not set when a ASN.1 structure is parsed using
      * OpenSSL::ASN1.decode.
      */
     rb_attr(cASN1Constructive, rb_intern("tagging"), 1, 1, Qtrue);
diff --git a/ext/openssl/ossl_bn.c b/ext/openssl/ossl_bn.c
index dfe1b268..b0e8356a 100644
--- a/ext/openssl/ossl_bn.c
+++ b/ext/openssl/ossl_bn.c
@@ -176,8 +176,7 @@ ossl_bn_alloc(VALUE klass)
     return obj;
 }
 
-/* Document-method: OpenSSL::BN.new
- *
+/*
  * call-seq:
  *    OpenSSL::BN.new => aBN
  *    OpenSSL::BN.new(bn) => aBN
@@ -185,7 +184,7 @@ ossl_bn_alloc(VALUE klass)
  *    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)
diff --git a/ext/openssl/ossl_cipher.c b/ext/openssl/ossl_cipher.c
index aed7fbb4..4ee76a97 100644
--- a/ext/openssl/ossl_cipher.c
+++ b/ext/openssl/ossl_cipher.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
diff --git a/ext/openssl/ossl_digest.c b/ext/openssl/ossl_digest.c
index fdafda00..b93fe91c 100644
--- a/ext/openssl/ossl_digest.c
+++ b/ext/openssl/ossl_digest.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')
diff --git a/ext/openssl/ossl_engine.c b/ext/openssl/ossl_engine.c
index e840bfd9..887a04dd 100644
--- a/ext/openssl/ossl_engine.c
+++ b/ext/openssl/ossl_engine.c
@@ -72,14 +72,13 @@ static const rb_data_type_t ossl_engine_type = {
     0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
 };
 
-/* Document-method: OpenSSL::Engine.load
- *
+/*
  * call-seq:
- *   load(enginename = nil)
+ *    OpenSSL::Engine.load(name = nil)
  *
- * This method loads engines. If +name+ is nil, then all builtin engines are
- * loaded. Otherwise, the given +name+, as a string,  is loaded if available to
- * your runtime, and returns true. If +name+ is not found, then nil is
+ * This method loads engines. If _name_ is nil, then all builtin engines are
+ * loaded. Otherwise, the given _name_, as a String,  is loaded if available to
+ * your runtime, and returns true. If _name_ is not found, then nil is
  * returned.
  *
  */
@@ -153,9 +152,9 @@ ossl_engine_s_load(int argc, VALUE *argv, VALUE klass)
 #endif /* HAVE_ENGINE_LOAD_BUILTIN_ENGINES */
 }
 
-/* Document-method: OpenSSL::Engine.cleanup
+/*
  * call-seq:
- *  OpenSSL::Engine.cleanup
+ *    OpenSSL::Engine.cleanup
  *
  * It is only necessary to run cleanup when engines are loaded via
  * OpenSSL::Engine.load. However, running cleanup before exit is recommended.
@@ -169,7 +168,9 @@ ossl_engine_s_cleanup(VALUE self)
     return Qnil;
 }
 
-/* Document-method: OpenSSL::Engine.engines
+/*
+ * call-seq:
+ *    OpenSSL::Engine.engines -> [engine, ...]
  *
  * Returns an array of currently loaded engines.
  */
@@ -193,17 +194,16 @@ ossl_engine_s_engines(VALUE klass)
     return ary;
 }
 
-/* Document-method: OpenSSL::Engine.by_id
- *
+/*
  * call-seq:
- *   by_id(name) -> engine
+ *    OpenSSL::Engine.by_id(name) -> engine
  *
- * Fetch the engine as specified by the +id+ String
+ * Fetches the engine as specified by the _id_ String.
  *
  *   OpenSSL::Engine.by_id("openssl")
  *    => #<OpenSSL::Engine id="openssl" name="Software engine support">
  *
- * See OpenSSL::Engine.engines for the currently loaded engines
+ * See OpenSSL::Engine.engines for the currently loaded engines.
  */
 static VALUE
 ossl_engine_s_by_id(VALUE klass, VALUE id)
@@ -227,9 +227,11 @@ ossl_engine_s_by_id(VALUE klass, VALUE id)
     return obj;
 }
 
-/* Document-method: OpenSSL::Engine#id
+/*
+ * call-seq:
+ *    engine.id -> string
  *
- * Get the id for this engine
+ * Gets the id for this engine.
  *
  *    OpenSSL::Engine.load
  *    OpenSSL::Engine.engines #=> [#<OpenSSL::Engine#>, ...]
@@ -244,9 +246,11 @@ ossl_engine_get_id(VALUE self)
     return rb_str_new2(ENGINE_get_id(e));
 }
 
-/* Document-method: OpenSSL::Engine#name
+/*
+ * call-seq:
+ *    engine.name -> string
  *
- * Get the descriptive name for this engine
+ * Get the descriptive name for this engine.
  *
  *    OpenSSL::Engine.load
  *    OpenSSL::Engine.engines #=> [#<OpenSSL::Engine#>, ...]
@@ -262,7 +266,9 @@ ossl_engine_get_name(VALUE self)
     return rb_str_new2(ENGINE_get_name(e));
 }
 
-/* Document-method: OpenSSL::Engine#finish
+/*
+ * call-seq:
+ *    engine.finish -> nil
  *
  * Releases all internal structural references for this engine.
  *
@@ -279,13 +285,12 @@ ossl_engine_finish(VALUE self)
     return Qnil;
 }
 
-/* Document-method: OpenSSL::Engine#cipher
- *
+/*
  * call-seq:
  *   engine.cipher(name) -> OpenSSL::Cipher
  *
- * This returns an OpenSSL::Cipher by +name+, if it is available in this
- * engine.
+ * Returns a new instance of OpenSSL::Cipher by _name_, if it is available in
+ * this engine.
  *
  * An EngineError will be raised if the cipher is unavailable.
  *
@@ -312,12 +317,11 @@ ossl_engine_get_cipher(VALUE self, VALUE name)
     return ossl_cipher_new(ciph);
 }
 
-/* Document-method: OpenSSL::Engine#digest
- *
+/*
  * call-seq:
  *   engine.digest(name) -> OpenSSL::Digest
  *
- * This returns an OpenSSL::Digest by +name+.
+ * Returns a new instance of OpenSSL::Digest by _name_.
  *
  * Will raise an EngineError if the digest is unavailable.
  *
@@ -345,12 +349,11 @@ ossl_engine_get_digest(VALUE self, VALUE name)
     return ossl_digest_new(md);
 }
 
-/* Document-method: OpenSSL::Engine#load_private_key
- *
+/*
  * call-seq:
  *    engine.load_private_key(id = nil, data = nil) -> OpenSSL::PKey
  *
- * Loads the given private key by +id+ and +data+.
+ * Loads the given private key identified by _id_ and _data_.
  *
  * An EngineError is raised of the OpenSSL::PKey is unavailable.
  *
@@ -375,12 +378,11 @@ ossl_engine_load_privkey(int argc, VALUE *argv, VALUE self)
     return obj;
 }
 
-/* Document-method: OpenSSL::Engine#load_public_key
- *
+/*
  * call-seq:
  *    engine.load_public_key(id = nil, data = nil) -> OpenSSL::PKey
  *
- * Loads the given private key by +id+ and +data+.
+ * Loads the given public key identified by _id_ and _data_.
  *
  * An EngineError is raised of the OpenSSL::PKey is unavailable.
  *
@@ -403,16 +405,15 @@ ossl_engine_load_pubkey(int argc, VALUE *argv, VALUE self)
     return ossl_pkey_new(pkey);
 }
 
-/* Document-method: OpenSSL::Engine#set_default
- *
+/*
  * call-seq:
  *    engine.set_default(flag)
  *
- * Set the defaults for this engine with the given +flag+.
+ * Set the defaults for this engine with the given _flag_.
  *
  * These flags are used to control combinations of algorithm methods.
  *
- * +flag+ can be one of the following, other flags are available depending on
+ * _flag_ can be one of the following, other flags are available depending on
  * your OS.
  *
  * [All flags]  0xFFFF
@@ -432,14 +433,13 @@ ossl_engine_set_default(VALUE self, VALUE flag)
     return Qtrue;
 }
 
-/* Document-method: OpenSSL::Engine#ctrl_cmd
- *
+/*
  * call-seq:
  *    engine.ctrl_cmd(command, value = nil) -> engine
  *
- * Send the given +command+ to this engine.
+ * Sends the given _command_ to this engine.
  *
- * Raises an EngineError if the +command+ fails.
+ * Raises an EngineError if the command fails.
  */
 static VALUE
 ossl_engine_ctrl_cmd(int argc, VALUE *argv, VALUE self)
@@ -469,7 +469,9 @@ ossl_engine_cmd_flag_to_name(int flag)
     }
 }
 
-/* Document-method: OpenSSL::Engine#cmds
+/*
+ * call-seq:
+ *    engine.cmds -> [["name", "description", "flags"], ...]
  *
  * Returns an array of command definitions for the current engine
  */
@@ -495,9 +497,11 @@ ossl_engine_get_cmds(VALUE self)
     return ary;
 }
 
-/* Document-method: OpenSSL::Engine#inspect
+/*
+ * call-seq:
+ *    engine.inspect -> string
  *
- * Pretty print this engine
+ * Pretty prints this engine.
  */
 static VALUE
 ossl_engine_inspect(VALUE self)
diff --git a/ext/openssl/ossl_hmac.c b/ext/openssl/ossl_hmac.c
index 270979ed..4e892b6c 100644
--- a/ext/openssl/ossl_hmac.c
+++ b/ext/openssl/ossl_hmac.c
@@ -135,7 +135,7 @@ ossl_hmac_copy(VALUE self, VALUE other)
  *  call-seq:
  *     hmac.update(string) -> self
  *
- * Returns +self+ updated with the message to be authenticated.
+ * Returns _hmac_ updated with the message to be authenticated.
  * Can be called repeatedly with chunks of the message.
  *
  * === Example
@@ -234,7 +234,7 @@ ossl_hmac_hexdigest(VALUE self)
  *  call-seq:
  *     hmac.reset -> self
  *
- * Returns +self+ as it was when it was first initialized, with all processed
+ * Returns _hmac_ as it was when it was first initialized, with all processed
  * data cleared from it.
  *
  * === Example
@@ -264,16 +264,16 @@ ossl_hmac_reset(VALUE self)
  *  call-seq:
  *     HMAC.digest(digest, key, data) -> aString
  *
- * Returns the authentication code as a binary string. The +digest+ parameter
- * must be an instance of OpenSSL::Digest.
+ * Returns the authentication code as a binary string. The _digest_ parameter
+ * specifies the digest algorithm to use. This may be a String representing
+ * the algorithm name or an instance of OpenSSL::Digest.
  *
  * === Example
  *
  *	key = 'key'
  * 	data = 'The quick brown fox jumps over the lazy dog'
- * 	digest = OpenSSL::Digest.new('sha1')
  *
- * 	hmac = OpenSSL::HMAC.digest(digest, key, data)
+ * 	hmac = OpenSSL::HMAC.digest('sha1', key, data)
  * 	#=> "\xDE|\x9B\x85\xB8\xB7\x8A\xA6\xBC\x8Az6\xF7\n\x90p\x1C\x9D\xB4\xD9"
  *
  */
@@ -295,16 +295,16 @@ ossl_hmac_s_digest(VALUE klass, VALUE digest, VALUE key, VALUE data)
  *  call-seq:
  *     HMAC.hexdigest(digest, key, data) -> aString
  *
- * Returns the authentication code as a hex-encoded string. The +digest+
- * parameter must be an instance of OpenSSL::Digest.
+ * Returns the authentication code as a hex-encoded string. The _digest_
+ * parameter specifies the digest algorithm to use. This may be a String
+ * representing the algorithm name or an instance of OpenSSL::Digest.
  *
  * === Example
  *
  *	key = 'key'
  * 	data = 'The quick brown fox jumps over the lazy dog'
- * 	digest = OpenSSL::Digest.new('sha1')
  *
- * 	hmac = OpenSSL::HMAC.hexdigest(digest, key, data)
+ * 	hmac = OpenSSL::HMAC.hexdigest('sha1', key, data)
  * 	#=> "de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9"
  *
  */
diff --git a/ext/openssl/ossl_ns_spki.c b/ext/openssl/ossl_ns_spki.c
index 98f6552e..a64b3d3f 100644
--- a/ext/openssl/ossl_ns_spki.c
+++ b/ext/openssl/ossl_ns_spki.c
@@ -73,7 +73,7 @@ ossl_spki_alloc(VALUE klass)
  *    SPKI.new([request]) => spki
  *
  * === Parameters
- * * +request+ - optional raw request, either in PEM or DER format.
+ * * _request_ - optional raw request, either in PEM or DER format.
  */
 static VALUE
 ossl_spki_initialize(int argc, VALUE *argv, VALUE self)
@@ -198,7 +198,7 @@ ossl_spki_get_public_key(VALUE self)
  *    spki.public_key = pub => pkey
  *
  * === Parameters
- * * +pub+ - the public key to be set for this instance
+ * * _pub_ - the public key to be set for this instance
  *
  * Sets the public key to be associated with the SPKI, an instance of
  * OpenSSL::PKey. This should be the public key corresponding to the
@@ -243,7 +243,7 @@ ossl_spki_get_challenge(VALUE self)
  *    spki.challenge = str => string
  *
  * === Parameters
- * * +str+ - the challenge string to be set for this instance
+ * * _str_ - the challenge string to be set for this instance
  *
  * Sets the challenge to be associated with the SPKI. May be used by the
  * server, e.g. to prevent replay.
@@ -268,8 +268,8 @@ ossl_spki_set_challenge(VALUE self, VALUE str)
  *    spki.sign(key, digest) => spki
  *
  * === Parameters
- * * +key+ - the private key to be used for signing this instance
- * * +digest+ - the digest to be used for signing this instance
+ * * _key_ - the private key to be used for signing this instance
+ * * _digest_ - the digest to be used for signing this instance
  *
  * To sign an SPKI, the private key corresponding to the public key set
  * for this instance should be used, in addition to a digest algorithm in
@@ -298,7 +298,7 @@ ossl_spki_sign(VALUE self, VALUE key, VALUE digest)
  *    spki.verify(key) => boolean
  *
  * === Parameters
- * * +key+ - the public key to be used for verifying the SPKI signature
+ * * _key_ - the public key to be used for verifying the SPKI signature
  *
  * Returns +true+ if the signature is valid, +false+ otherwise. To verify an
  * SPKI, the public key contained within the SPKI should be used.
diff --git a/ext/openssl/ossl_ocsp.c b/ext/openssl/ossl_ocsp.c
index a8b3503d..cc36d21b 100644
--- a/ext/openssl/ossl_ocsp.c
+++ b/ext/openssl/ossl_ocsp.c
@@ -218,7 +218,7 @@ ossl_ocspreq_initialize_copy(VALUE self, VALUE other)
  *   OpenSSL::OCSP::Request.new(request_der) -> request
  *
  * Creates a new OpenSSL::OCSP::Request.  The request may be created empty or
- * from a +request_der+ string.
+ * from a _request_der_ string.
  */
 
 static VALUE
@@ -248,7 +248,7 @@ ossl_ocspreq_initialize(int argc, VALUE *argv, VALUE self)
  * call-seq:
  *   request.add_nonce(nonce = nil) -> request
  *
- * Adds a +nonce+ to the OCSP request.  If no nonce is given a random one will
+ * Adds a _nonce_ to the OCSP request.  If no nonce is given a random one will
  * be generated.
  *
  * The nonce is used to prevent replay attacks but some servers do not support
@@ -281,7 +281,7 @@ ossl_ocspreq_add_nonce(int argc, VALUE *argv, VALUE self)
  * call-seq:
  *   request.check_nonce(response) -> result
  *
- * Checks the nonce validity for this request and +response+.
+ * Checks the nonce validity for this request and _response_.
  *
  * The return value is one of the following:
  *
@@ -291,7 +291,7 @@ ossl_ocspreq_add_nonce(int argc, VALUE *argv, VALUE self)
  *  2 :: nonces both absent.
  *  3 :: nonce present in response only.
  *
- * For most responses, clients can check +result+ > 0.  If a responder doesn't
+ * For most responses, clients can check _result_ > 0.  If a responder doesn't
  * handle nonces <code>result.nonzero?</code> may be necessary.  A result of
  * <code>0</code> is always an error.
  */
@@ -314,7 +314,7 @@ ossl_ocspreq_check_nonce(VALUE self, VALUE basic_resp)
  * call-seq:
  *   request.add_certid(certificate_id) -> request
  *
- * Adds +certificate_id+ to the request.
+ * Adds _certificate_id_ to the request.
  */
 
 static VALUE
@@ -371,17 +371,17 @@ ossl_ocspreq_get_certid(VALUE self)
  * call-seq:
  *   request.sign(cert, key, certs = nil, flags = 0, digest = nil) -> self
  *
- * Signs this OCSP request using +cert+, +key+ and optional +digest+. If
- * +digest+ is not specified, SHA-1 is used. +certs+ is an optional Array of
+ * Signs this OCSP request using _cert_, _key_ and optional _digest_. If
+ * _digest_ is not specified, SHA-1 is used. _certs_ is an optional Array of
  * additional certificates which are included in the request in addition to
- * the signer certificate. Note that if +certs+ is nil or not given, flag
+ * the signer certificate. Note that if _certs_ is +nil+ or not given, flag
  * OpenSSL::OCSP::NOCERTS is enabled. Pass an empty array to include only the
  * signer certificate.
  *
- * +flags+ can be a bitwise OR of the following constants:
+ * _flags_ is a bitwise OR of the following constants:
  *
  * OpenSSL::OCSP::NOCERTS::
- *   Don't include any certificates in the request. +certs+ will be ignored.
+ *   Don't include any certificates in the request. _certs_ will be ignored.
  */
 static VALUE
 ossl_ocspreq_sign(int argc, VALUE *argv, VALUE self)
@@ -421,8 +421,8 @@ ossl_ocspreq_sign(int argc, VALUE *argv, VALUE self)
  * call-seq:
  *   request.verify(certificates, store, flags = 0) -> true or false
  *
- * Verifies this request using the given +certificates+ and +store+.
- * +certificates+ is an array of OpenSSL::X509::Certificate, +store+ is an
+ * Verifies this request using the given _certificates_ and _store_.
+ * _certificates_ is an array of OpenSSL::X509::Certificate, _store_ is an
  * OpenSSL::X509::Store.
  */
 
@@ -479,7 +479,7 @@ ossl_ocspreq_to_der(VALUE self)
 /* call-seq:
  *   OpenSSL::OCSP::Response.create(status, basic_response = nil) -> response
  *
- * Creates an OpenSSL::OCSP::Response from +status+ and +basic_response+.
+ * Creates an OpenSSL::OCSP::Response from _status_ and _basic_response_.
  */
 
 static VALUE
@@ -539,7 +539,7 @@ ossl_ocspres_initialize_copy(VALUE self, VALUE other)
  *   OpenSSL::OCSP::Response.new(response_der) -> response
  *
  * Creates a new OpenSSL::OCSP::Response.  The response may be created empty or
- * from a +response_der+ string.
+ * from a _response_der_ string.
  */
 
 static VALUE
@@ -693,7 +693,7 @@ ossl_ocspbres_initialize_copy(VALUE self, VALUE other)
  * call-seq:
  *   OpenSSL::OCSP::BasicResponse.new(der_string = nil) -> basic_response
  *
- * Creates a new BasicResponse. If +der_string+ is given, decodes +der_string+
+ * Creates a new BasicResponse. If _der_string_ is given, decodes _der_string_
  * as DER.
  */
 
@@ -724,7 +724,7 @@ ossl_ocspbres_initialize(int argc, VALUE *argv, VALUE self)
  * call-seq:
  *   basic_response.copy_nonce(request) -> Integer
  *
- * Copies the nonce from +request+ into this response.  Returns 1 on success
+ * Copies the nonce from _request_ into this response.  Returns 1 on success
  * and 0 on failure.
  */
 
@@ -746,7 +746,7 @@ ossl_ocspbres_copy_nonce(VALUE self, VALUE request)
  * call-seq:
  *   basic_response.add_nonce(nonce = nil)
  *
- * Adds +nonce+ to this response.  If no nonce was provided a random nonce
+ * Adds _nonce_ to this response.  If no nonce was provided a random nonce
  * will be added.
  */
 
@@ -792,26 +792,26 @@ add_status_convert_time(VALUE obj)
  * call-seq:
  *   basic_response.add_status(certificate_id, status, reason, revocation_time, this_update, next_update, extensions) -> basic_response
  *
- * Adds a certificate status for +certificate_id+. +status+ is the status, and
+ * Adds a certificate status for _certificate_id_. _status_ is the status, and
  * must be one of these:
  *
  * - OpenSSL::OCSP::V_CERTSTATUS_GOOD
  * - OpenSSL::OCSP::V_CERTSTATUS_REVOKED
  * - OpenSSL::OCSP::V_CERTSTATUS_UNKNOWN
  *
- * +reason+ and +revocation_time+ can be given only when +status+ is
- * OpenSSL::OCSP::V_CERTSTATUS_REVOKED. +reason+ describes the reason for the
+ * _reason_ and _revocation_time_ can be given only when _status_ is
+ * OpenSSL::OCSP::V_CERTSTATUS_REVOKED. _reason_ describes the reason for the
  * revocation, and must be one of OpenSSL::OCSP::REVOKED_STATUS_* constants.
- * +revocation_time+ is the time when the certificate is revoked.
+ * _revocation_time_ is the time when the certificate is revoked.
  *
- * +this_update+ and +next_update+ indicate the time at which ths status is
+ * _this_update_ and _next_update_ indicate the time at which ths status is
  * verified to be correct and the time at or before which newer information
- * will be available, respectively. +next_update+ is optional.
+ * will be available, respectively. _next_update_ is optional.
  *
- * +extensions+ is an Array of OpenSSL::X509::Extension to be included in the
+ * _extensions_ is an Array of OpenSSL::X509::Extension to be included in the
  * SingleResponse. This is also optional.
  *
- * Note that the times, +revocation_time+, +this_update+ and +next_update+
+ * Note that the times, _revocation_time_, _this_update_ and _next_update_
  * can be specified in either of Integer or Time object. If they are Integer, it
  * is treated as the relative seconds from the current time.
  */
@@ -888,7 +888,7 @@ ossl_ocspbres_add_status(VALUE self, VALUE cid, VALUE status,
  * Returns an Array of statuses for this response.  Each status contains a
  * CertificateId, the status (0 for good, 1 for revoked, 2 for unknown), the
  * reason for the status, the revocation time, the time of this update, the time
- * for the next update and a list of OpenSSL::X509::Extensions.
+ * for the next update and a list of OpenSSL::X509::Extension.
  *
  * This should be superseded by BasicResponse#responses and #find_response that
  * return SingleResponse.
@@ -977,7 +977,7 @@ ossl_ocspbres_get_responses(VALUE self)
  * call-seq:
  *   basic_response.find_response(certificate_id) -> SingleResponse | nil
  *
- * Returns a SingleResponse whose CertId matches with +certificate_id+, or nil
+ * Returns a SingleResponse whose CertId matches with _certificate_id_, or +nil+
  * if this BasicResponse does not contain it.
  */
 static VALUE
@@ -1006,10 +1006,10 @@ ossl_ocspbres_find_response(VALUE self, VALUE target)
  * call-seq:
  *   basic_response.sign(cert, key, certs = nil, flags = 0, digest = nil) -> self
  *
- * Signs this OCSP response using the +cert+, +key+ and optional +digest+. This
+ * Signs this OCSP response using the _cert_, _key_ and optional _digest_. This
  * behaves in the similar way as OpenSSL::OCSP::Request#sign.
  *
- * +flags+ can include:
+ * _flags_ can include:
  * OpenSSL::OCSP::NOCERTS::    don't include certificates
  * OpenSSL::OCSP::NOTIME::     don't set producedAt
  * OpenSSL::OCSP::RESPID_KEY:: use signer's public key hash as responderID
@@ -1053,8 +1053,8 @@ ossl_ocspbres_sign(int argc, VALUE *argv, VALUE self)
  * call-seq:
  *   basic_response.verify(certificates, store, flags = 0) -> true or false
  *
- * Verifies the signature of the response using the given +certificates+ and
- * +store+. This works in the similar way as OpenSSL::OCSP::Request#verify.
+ * Verifies the signature of the response using the given _certificates_ and
+ * _store_. This works in the similar way as OpenSSL::OCSP::Request#verify.
  */
 static VALUE
 ossl_ocspbres_verify(int argc, VALUE *argv, VALUE self)
@@ -1184,7 +1184,7 @@ ossl_ocspsres_alloc(VALUE klass)
  * call-seq:
  *   OpenSSL::OCSP::SingleResponse.new(der_string) -> SingleResponse
  *
- * Creates a new SingleResponse from +der_string+.
+ * Creates a new SingleResponse from _der_string_.
  */
 static VALUE
 ossl_ocspsres_initialize(VALUE self, VALUE arg)
@@ -1235,10 +1235,10 @@ ossl_ocspsres_initialize_copy(VALUE self, VALUE other)
  *
  * It is possible that the OCSP request takes a few seconds or the time is not
  * accurate. To avoid rejecting a valid response, this method allows the times
- * to be within +nsec+ of the current time.
+ * to be within _nsec_ seconds of the current time.
  *
  * Some responders don't set the nextUpdate field. This may cause a very old
- * response to be considered valid. The +maxsec+ parameter can be used to limit
+ * response to be considered valid. The _maxsec_ parameter can be used to limit
  * the age of responses.
  */
 static VALUE
@@ -1485,14 +1485,13 @@ ossl_ocspcid_initialize_copy(VALUE self, VALUE other)
  *   OpenSSL::OCSP::CertificateId.new(subject, issuer, digest = nil) -> certificate_id
  *   OpenSSL::OCSP::CertificateId.new(der_string)                    -> certificate_id
  *
- * Creates a new OpenSSL::OCSP::CertificateId for the given +subject+ and
- * +issuer+ X509 certificates.  The +digest+ is used to compute the
- * certificate ID and must be an OpenSSL::Digest instance.
+ * Creates a new OpenSSL::OCSP::CertificateId for the given _subject_ and
+ * _issuer_ X509 certificates.  The _digest_ is a digest algorithm that is used
+ * to compute the hash values. This defaults to SHA-1.
  *
  * If only one argument is given, decodes it as DER representation of a
  * certificate ID.
  */
-
 static VALUE
 ossl_ocspcid_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -1534,7 +1533,7 @@ ossl_ocspcid_initialize(int argc, VALUE *argv, VALUE self)
  * call-seq:
  *   certificate_id.cmp(other) -> true or false
  *
- * Compares this certificate id with +other+ and returns true if they are the
+ * Compares this certificate id with _other_ and returns +true+ if they are the
  * same.
  */
 static VALUE
@@ -1554,7 +1553,7 @@ ossl_ocspcid_cmp(VALUE self, VALUE other)
  * call-seq:
  *   certificate_id.cmp_issuer(other) -> true or false
  *
- * Compares this certificate id's issuer with +other+ and returns true if
+ * Compares this certificate id's issuer with _other_ and returns +true+ if
  * they are the same.
  */
 
diff --git a/ext/openssl/ossl_pkcs12.c b/ext/openssl/ossl_pkcs12.c
index 0b9c7816..6a395cfa 100644
--- a/ext/openssl/ossl_pkcs12.c
+++ b/ext/openssl/ossl_pkcs12.c
@@ -89,20 +89,20 @@ ossl_pkcs12_initialize_copy(VALUE self, VALUE other)
  *    PKCS12.create(pass, name, key, cert [, ca, [, key_pbe [, cert_pbe [, key_iter [, mac_iter [, keytype]]]]]])
  *
  * === Parameters
- * * +pass+ - string
- * * +name+ - A string describing the key.
- * * +key+ - Any PKey.
- * * +cert+ - A X509::Certificate.
+ * * _pass_ - string
+ * * _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.
- * * +ca+ - An optional array of X509::Certificate's.
- * * +key_pbe+ - string
- * * +cert_pbe+ - string
- * * +key_iter+ - integer
- * * +mac_iter+ - integer
- * * +keytype+ - An integer representing an MSIE specific extension.
+ * * _ca_ - An optional array of X509::Certificate's.
+ * * _key_pbe_ - string
+ * * _cert_pbe_ - string
+ * * _key_iter_ - integer
+ * * _mac_iter_ - integer
+ * * _keytype_ - An integer representing an MSIE specific extension.
  *
- * Any optional arguments may be supplied as nil to preserve the OpenSSL defaults.
+ * Any optional arguments may be supplied as +nil+ to preserve the OpenSSL defaults.
  *
  * See the OpenSSL documentation for PKCS12_create().
  */
@@ -161,8 +161,8 @@ ossl_pkcs12_s_create(int argc, VALUE *argv, VALUE self)
  *    PKCS12.new(str, pass) -> pkcs12
  *
  * === Parameters
- * * +str+ - Must be a DER encoded PKCS12 string.
- * * +pass+ - string
+ * * _str_ - Must be a DER encoded PKCS12 string.
+ * * _pass_ - string
  */
 static VALUE
 ossl_pkcs12_initialize(int argc, VALUE *argv, VALUE self)
diff --git a/ext/openssl/ossl_pkey.c b/ext/openssl/ossl_pkey.c
index e161277d..47990319 100644
--- a/ext/openssl/ossl_pkey.c
+++ b/ext/openssl/ossl_pkey.c
@@ -123,15 +123,15 @@ ossl_pkey_new(EVP_PKEY *pkey)
  *     OpenSSL::PKey.read(string [, pwd ]) -> PKey
  *     OpenSSL::PKey.read(io [, pwd ]) -> PKey
  *
- * Reads a DER or PEM encoded string from +string+ or +io+ and returns an
+ * Reads a DER or PEM encoded string from _string_ or _io_ and returns an
  * instance of the appropriate PKey class.
  *
  * === Parameters
- * * +string+ is a DER- or PEM-encoded string containing an arbitrary private
+ * * _string+ is a DER- or PEM-encoded string containing an arbitrary private
  *   or public key.
- * * +io+ is an instance of +IO+ containing a DER- or PEM-encoded
+ * * _io_ is an instance of IO containing a DER- or PEM-encoded
  *   arbitrary private or public key.
- * * +pwd+ is an optional password in case +string+ or +file+ is an encrypted
+ * * _pwd_ is an optional password in case _string_ or _io_ is an encrypted
  *   PEM resource.
  */
 static VALUE
@@ -259,7 +259,7 @@ ossl_pkey_alloc(VALUE klass)
  *      PKeyClass.new -> self
  *
  * Because PKey is an abstract class, actually calling this method explicitly
- * will raise a +NotImplementedError+.
+ * will raise a NotImplementedError.
  */
 static VALUE
 ossl_pkey_initialize(VALUE self)
@@ -274,10 +274,10 @@ ossl_pkey_initialize(VALUE self)
  *  call-seq:
  *      pkey.sign(digest, data) -> String
  *
- * To sign the +String+ +data+, +digest+, an instance of OpenSSL::Digest, must
- * be provided. The return value is again a +String+ containing the signature.
+ * To sign the String _data_, _digest_, an instance of OpenSSL::Digest, must
+ * be provided. The return value is again a String containing the signature.
  * A PKeyError is raised should errors occur.
- * Any previous state of the +Digest+ instance is irrelevant to the signature
+ * Any previous state of the Digest instance is irrelevant to the signature
  * outcome, the digest instance is reset to its initial state during the
  * operation.
  *
@@ -326,12 +326,12 @@ ossl_pkey_sign(VALUE self, VALUE digest, VALUE data)
  *  call-seq:
  *      pkey.verify(digest, signature, data) -> String
  *
- * To verify the +String+ +signature+, +digest+, an instance of
+ * To verify the String _signature_, _digest_, an instance of
  * OpenSSL::Digest, must be provided to re-compute the message digest of the
- * original +data+, also a +String+. The return value is +true+ if the
+ * original _data_, also a String. The return value is +true+ if the
  * signature is valid, +false+ otherwise. A PKeyError is raised should errors
  * occur.
- * Any previous state of the +Digest+ instance is irrelevant to the validation
+ * Any previous state of the Digest instance is irrelevant to the validation
  * outcome, the digest instance is reset to its initial state during the
  * operation.
  *
diff --git a/ext/openssl/ossl_pkey_dh.c b/ext/openssl/ossl_pkey_dh.c
index dd85b7b9..48e898b5 100644
--- a/ext/openssl/ossl_pkey_dh.c
+++ b/ext/openssl/ossl_pkey_dh.c
@@ -150,8 +150,8 @@ dh_generate(int size, int gen)
  * components alike.
  *
  * === Parameters
- * * +size+ is an integer representing the desired key size. Keys smaller than 1024 bits should be considered insecure.
- * * +generator+ is a small number > 1, typically 2 or 5.
+ * * _size_ is an integer representing the desired key size. Keys smaller than 1024 bits should be considered insecure.
+ * * _generator_ is a small number > 1, typically 2 or 5.
  *
  */
 static VALUE
@@ -181,15 +181,15 @@ ossl_dh_s_generate(int argc, VALUE *argv, VALUE klass)
  *   DH.new(size [, generator]) -> dh
  *
  * Either generates a DH instance from scratch or by reading already existing
- * DH parameters from +string+. Note that when reading a DH instance from
+ * DH parameters from _string_. Note that when reading a DH instance from
  * data that was encoded from a DH instance by using DH#to_pem or DH#to_der
  * the result will *not* contain a public/private key pair yet. This needs to
  * be generated using DH#generate_key! first.
  *
  * === Parameters
- * * +size+ is an integer representing the desired key size. Keys smaller than 1024 bits should be considered insecure.
- * * +generator+ is a small number > 1, typically 2 or 5.
- * * +string+ contains the DER or PEM encoded key.
+ * * _size_ is an integer representing the desired key size. Keys smaller than 1024 bits should be considered insecure.
+ * * _generator_ is a small number > 1, typically 2 or 5.
+ * * _string_ contains the DER or PEM encoded key.
  *
  * === Examples
  *  DH.new # -> dh
@@ -436,7 +436,7 @@ ossl_dh_to_text(VALUE self)
  *     dh.public_key -> aDH
  *
  * Returns a new DH instance that carries just the public information, i.e.
- * the prime +p+ and the generator +g+, but no public/private key yet. Such
+ * the prime _p_ and the generator _g_, but no public/private key yet. Such
  * a pair may be generated using DH#generate_key!. The "public key" needed
  * for a key exchange with DH#compute_key is considered as per-session
  * information and may be retrieved with DH#pub_key once a key pair has
@@ -526,7 +526,7 @@ ossl_dh_generate_key(VALUE self)
  * See DH_compute_key() for further information.
  *
  * === Parameters
- * * +pub_bn+ is a OpenSSL::BN, *not* the DH instance returned by
+ * * _pub_bn_ is a OpenSSL::BN, *not* the DH instance returned by
  *   DH#public_key as that contains the DH parameters only.
  */
 static VALUE
@@ -557,7 +557,7 @@ ossl_dh_compute_key(VALUE self, VALUE pub)
  * call-seq:
  *   dh.set_pqg(p, q, g) -> self
  *
- * Sets +p+, +q+, +g+ for the DH instance.
+ * Sets _p_, _q_, _g_ to the DH instance.
  */
 OSSL_PKEY_BN_DEF3(dh, DH, pqg, p, q, g)
 /*
@@ -565,7 +565,7 @@ OSSL_PKEY_BN_DEF3(dh, DH, pqg, p, q, g)
  * call-seq:
  *   dh.set_key(pub_key, priv_key) -> self
  *
- * Sets +pub_key+ and +priv_key+ for the DH instance. +priv_key+ may be nil.
+ * Sets _pub_key_ and _priv_key_ for the DH instance. _priv_key_ may be +nil+.
  */
 OSSL_PKEY_BN_DEF2(dh, DH, key, pub_key, priv_key)
 
diff --git a/ext/openssl/ossl_pkey_dsa.c b/ext/openssl/ossl_pkey_dsa.c
index b21abc42..53d5c8d9 100644
--- a/ext/openssl/ossl_pkey_dsa.c
+++ b/ext/openssl/ossl_pkey_dsa.c
@@ -172,7 +172,7 @@ dsa_generate(int size)
  * from scratch.
  *
  * === Parameters
- * * +size+ is an integer representing the desired key size.
+ * * _size_ is an integer representing the desired key size.
  *
  */
 static VALUE
@@ -195,12 +195,12 @@ ossl_dsa_s_generate(VALUE klass, VALUE size)
  *    DSA.new(size) -> dsa
  *    DSA.new(string [, pass]) -> dsa
  *
- * Creates a new DSA instance by reading an existing key from +string+.
+ * Creates a new DSA instance by reading an existing key from _string_.
  *
  * === Parameters
- * * +size+ is an integer representing the desired key size.
- * * +string+ contains a DER or PEM encoded key.
- * * +pass+ is a string that contains an optional password.
+ * * _size_ is an integer representing the desired key size.
+ * * _string_ contains a DER or PEM encoded key.
+ * * _pass_ is a string that contains an optional password.
  *
  * === Examples
  *  DSA.new -> dsa
@@ -329,8 +329,8 @@ ossl_dsa_is_private(VALUE self)
  * Encodes this DSA to its PEM encoding.
  *
  * === Parameters
- * * +cipher+ is an OpenSSL::Cipher.
- * * +password+ is a string containing your password.
+ * * _cipher_ is an OpenSSL::Cipher.
+ * * _password_ is a string containing your password.
  *
  * === Examples
  *  DSA.to_pem -> aString
@@ -503,12 +503,12 @@ ossl_dsa_to_public_key(VALUE self)
  *  call-seq:
  *    dsa.syssign(string) -> aString
  *
- * Computes and returns the DSA signature of +string+, where +string+ is
+ * Computes and returns the DSA signature of _string_, where _string_ is
  * expected to be an already-computed message digest of the original input
  * data. The signature is issued using the private key of this DSA instance.
  *
  * === Parameters
- * * +string+ is a message digest of the original input data to be signed
+ * * _string_ is a message digest of the original input data to be signed.
  *
  * === Example
  *  dsa = OpenSSL::PKey::DSA.new(2048)
@@ -549,11 +549,11 @@ ossl_dsa_sign(VALUE self, VALUE data)
  *    dsa.sysverify(digest, sig) -> true | false
  *
  * Verifies whether the signature is valid given the message digest input. It
- * does so by validating +sig+ using the public key of this DSA instance.
+ * does so by validating _sig_ using the public key of this DSA instance.
  *
  * === Parameters
- * * +digest+ is a message digest of the original input data to be signed
- * * +sig+ is a DSA signature value
+ * * _digest_ is a message digest of the original input data to be signed
+ * * _sig_ is a DSA signature value
  *
  * === Example
  *  dsa = OpenSSL::PKey::DSA.new(2048)
@@ -590,7 +590,7 @@ ossl_dsa_verify(VALUE self, VALUE digest, VALUE sig)
  * call-seq:
  *   dsa.set_pqg(p, q, g) -> self
  *
- * Sets +p+, +q+, +g+ for the DSA instance.
+ * Sets _p_, _q_, _g_ to the DSA instance.
  */
 OSSL_PKEY_BN_DEF3(dsa, DSA, pqg, p, q, g)
 /*
@@ -598,7 +598,7 @@ OSSL_PKEY_BN_DEF3(dsa, DSA, pqg, p, q, g)
  * call-seq:
  *   dsa.set_key(pub_key, priv_key) -> self
  *
- * Sets +pub_key+ and +priv_key+ for the DSA instance. +priv_key+ may be nil.
+ * Sets _pub_key_ and _priv_key_ for the DSA instance. _priv_key_ may be +nil+.
  */
 OSSL_PKEY_BN_DEF2(dsa, DSA, key, pub_key, priv_key)
 
diff --git a/ext/openssl/ossl_pkey_ec.c b/ext/openssl/ossl_pkey_ec.c
index ce347516..f0e27461 100644
--- a/ext/openssl/ossl_pkey_ec.c
+++ b/ext/openssl/ossl_pkey_ec.c
@@ -275,7 +275,7 @@ ossl_ec_key_initialize_copy(VALUE self, VALUE other)
  *   key.group   => group
  *
  * Returns the EC::Group that the key is associated with. Modifying the returned
- * group does not affect +key+.
+ * group does not affect _key_.
  */
 static VALUE
 ossl_ec_key_get_group(VALUE self)
@@ -296,7 +296,7 @@ ossl_ec_key_get_group(VALUE self)
  *   key.group = group
  *
  * Sets the EC::Group for the key. The group structure is internally copied so
- * modifition to +group+ after assigning to a key has no effect on the key.
+ * modifition to _group_ after assigning to a key has no effect on the key.
  */
 static VALUE
 ossl_ec_key_set_group(VALUE self, VALUE group_v)
@@ -502,8 +502,8 @@ 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
+ * 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.
  */
@@ -724,7 +724,7 @@ ec_group_new(const EC_GROUP *group)
  *
  * Creates a new EC::Group object.
  *
- * +ec_method+ is a symbol that represents an EC_METHOD. Currently the following
+ * _ec_method_ is a symbol that represents an EC_METHOD. Currently the following
  * are supported:
  *
  * * :GFp_simple
@@ -862,8 +862,8 @@ ossl_ec_group_initialize_copy(VALUE self, VALUE other)
  *   group1.eql?(group2)   => true | false
  *   group1 == group2   => true | false
  *
- * Returns true if the two groups use the same curve and have the same
- * parameters, false otherwise.
+ * Returns +true+ if the two groups use the same curve and have the same
+ * parameters, +false+ otherwise.
  */
 static VALUE ossl_ec_group_eql(VALUE a, VALUE b)
 {
@@ -903,8 +903,8 @@ static VALUE ossl_ec_group_get_generator(VALUE self)
  * call-seq:
  *   group.set_generator(generator, order, cofactor)   => self
  *
- * Sets the curve parameters. +generator+ must be an instance of EC::Point that
- * is on the curve. +order+ and +cofactor+ are integers.
+ * Sets the curve parameters. _generator_ must be an instance of EC::Point that
+ * is on the curve. _order_ and _cofactor_ are integers.
  *
  * See the OpenSSL documentation for EC_GROUP_set_generator()
  */
@@ -1127,14 +1127,14 @@ parse_point_conversion_form_symbol(VALUE sym)
  *
  * Sets the form how EC::Point data is encoded as ASN.1 as defined in X9.62.
  *
- * +format+ can be one of these:
+ * _format_ can be one of these:
  *
- * :compressed::
+ * +:compressed+::
  *   Encoded as z||x, where z is an octet indicating which solution of the
  *   equation y is. z will be 0x02 or 0x03.
- * :uncompressed::
+ * +:uncompressed+::
  *   Encoded as z||x||y, where z is an octet 0x04.
- * :hybrid::
+ * +:hybrid+::
  *   Encodes as z||x||y, where z is an octet indicating which solution of the
  *   equation y is. z will be 0x06 or 0x07.
  *
@@ -1558,7 +1558,7 @@ static VALUE ossl_ec_point_set_to_infinity(VALUE self)
  *   point.to_bn(conversion_form = nil) => OpenSSL::BN
  *
  * Convert the EC point into an octet string and store in an OpenSSL::BN. If
- * +conversion_form+ is given, the point data is converted using the specified
+ * _conversion_form_ is given, the point data is converted using the specified
  * form. If not given, the default form set in the EC::Group object is used.
  *
  * See also EC::Point#point_conversion_form=.
@@ -1597,12 +1597,12 @@ ossl_ec_point_to_bn(int argc, VALUE *argv, VALUE self)
  * Performs elliptic curve point multiplication.
  *
  * The first form calculates <tt>bn1 * point + bn2 * G</tt>, where +G+ is the
- * generator of the group of +point+. +bn2+ may be ommitted, and in that case,
+ * generator of the group of _point_. _bn2_ may be ommitted, and in that case,
  * the result is just <tt>bn1 * point</tt>.
  *
  * The second form calculates <tt>bns[0] * point + bns[1] * points[0] + ...
- * + bns[-1] * points[-1] + bn2 * G</tt>. +bn2+ may be ommitted. +bns+ must be
- * an array of OpenSSL::BN. +points+ must be an array of
+ * + bns[-1] * points[-1] + bn2 * G</tt>. _bn2_ may be ommitted. _bns_ must be
+ * an array of OpenSSL::BN. _points_ must be an array of
  * OpenSSL::PKey::EC::Point. Please note that <tt>points[0]</tt> is not
  * multiplied by <tt>bns[0]</tt>, but <tt>bns[1]</tt>.
  */
diff --git a/ext/openssl/ossl_pkey_rsa.c b/ext/openssl/ossl_pkey_rsa.c
index cea228d6..59c12f5c 100644
--- a/ext/openssl/ossl_pkey_rsa.c
+++ b/ext/openssl/ossl_pkey_rsa.c
@@ -172,8 +172,8 @@ rsa_generate(int size, unsigned long exp)
  *   RSA.generate(size)           => RSA instance
  *   RSA.generate(size, exponent) => RSA instance
  *
- * Generates an RSA keypair.  +size+ is an integer representing the desired key
- * size.  Keys smaller than 1024 should be considered insecure.  +exponent+ is
+ * Generates an RSA keypair.  _size_ is an integer representing the desired key
+ * size.  Keys smaller than 1024 should be considered insecure.  _exponent_ is
  * an odd number normally 3, 17, or 65537.
  */
 static VALUE
@@ -203,12 +203,12 @@ ossl_rsa_s_generate(int argc, VALUE *argv, VALUE klass)
  *   RSA.new(encoded_key)              => RSA instance
  *   RSA.new(encoded_key, pass_phrase) => RSA instance
  *
- * Generates or loads an RSA keypair.  If an integer +key_size+ is given it
+ * Generates or loads an RSA keypair.  If an integer _key_size_ is given it
  * represents the desired key size.  Keys less than 1024 bits should be
  * considered insecure.
  *
- * A key can instead be loaded from an +encoded_key+ which must be PEM or DER
- * encoded.  A +pass_phrase+ can be used to decrypt the key.  If none is given
+ * A key can instead be loaded from an _encoded_key_ which must be PEM or DER
+ * encoded.  A _pass_phrase_ can be used to decrypt the key.  If none is given
  * OpenSSL will prompt for the pass phrase.
  *
  * = Examples
@@ -295,7 +295,7 @@ ossl_rsa_initialize_copy(VALUE self, VALUE other)
  * call-seq:
  *   rsa.public? => true
  *
- * The return value is always true since every private key is also a public
+ * The return value is always +true+ since every private key is also a public
  * key.
  */
 static VALUE
@@ -333,8 +333,8 @@ ossl_rsa_is_private(VALUE self)
  *   rsa.to_pem([cipher, pass_phrase]) => PEM-format String
  *   rsa.to_s([cipher, pass_phrase]) => PEM-format String
  *
- * 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
+ * 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 instance.
  */
 static VALUE
@@ -409,7 +409,7 @@ ossl_rsa_to_der(VALUE self)
  *   rsa.public_encrypt(string)          => String
  *   rsa.public_encrypt(string, padding) => String
  *
- * Encrypt +string+ with the public key.  +padding+ defaults to PKCS1_PADDING.
+ * Encrypt _string_ with the public key.  _padding_ defaults to PKCS1_PADDING.
  * The encrypted string output can be decrypted using #private_decrypt.
  */
 static VALUE
@@ -441,8 +441,8 @@ ossl_rsa_public_encrypt(int argc, VALUE *argv, VALUE self)
  *   rsa.public_decrypt(string)          => String
  *   rsa.public_decrypt(string, padding) => String
  *
- * Decrypt +string+, which has been encrypted with the private key, with the
- * public key.  +padding+ defaults to PKCS1_PADDING.
+ * Decrypt _string_, which has been encrypted with the private key, with the
+ * public key.  _padding_ defaults to PKCS1_PADDING.
  */
 static VALUE
 ossl_rsa_public_decrypt(int argc, VALUE *argv, VALUE self)
@@ -473,7 +473,7 @@ ossl_rsa_public_decrypt(int argc, VALUE *argv, VALUE self)
  *   rsa.private_encrypt(string)          => String
  *   rsa.private_encrypt(string, padding) => String
  *
- * Encrypt +string+ with the private key.  +padding+ defaults to PKCS1_PADDING.
+ * Encrypt _string_ with the private key.  _padding_ defaults to PKCS1_PADDING.
  * The encrypted string output can be decrypted using #public_decrypt.
  */
 static VALUE
@@ -507,8 +507,8 @@ ossl_rsa_private_encrypt(int argc, VALUE *argv, VALUE self)
  *   rsa.private_decrypt(string)          => String
  *   rsa.private_decrypt(string, padding) => String
  *
- * Decrypt +string+, which has been encrypted with the public key, with the
- * private key.  +padding+ defaults to PKCS1_PADDING.
+ * Decrypt _string_, which has been encrypted with the public key, with the
+ * private key.  _padding_ defaults to PKCS1_PADDING.
  */
 static VALUE
 ossl_rsa_private_decrypt(int argc, VALUE *argv, VALUE self)
@@ -659,7 +659,7 @@ ossl_rsa_blinding_off(VALUE self)
  * call-seq:
  *   rsa.set_key(n, e, d) -> self
  *
- * Sets +n+, +e+, +d+ for the RSA instance.
+ * Sets _n_, _e_, _d_ for the RSA instance.
  */
 OSSL_PKEY_BN_DEF3(rsa, RSA, key, n, e, d)
 /*
@@ -667,7 +667,7 @@ OSSL_PKEY_BN_DEF3(rsa, RSA, key, n, e, d)
  * call-seq:
  *   rsa.set_factors(p, q) -> self
  *
- * Sets +p+, +q+ for the RSA instance.
+ * Sets _p_, _q_ for the RSA instance.
  */
 OSSL_PKEY_BN_DEF2(rsa, RSA, factors, p, q)
 /*
@@ -675,7 +675,7 @@ OSSL_PKEY_BN_DEF2(rsa, RSA, factors, p, q)
  * call-seq:
  *   rsa.set_crt_params(dmp1, dmq1, iqmp) -> self
  *
- * Sets +dmp1+, +dmq1+, +iqmp+ for the RSA instance. They are calculated by
+ * Sets _dmp1_, _dmq1_, _iqmp_ for the RSA instance. They are calculated by
  * <tt>d mod (p - 1)</tt>, <tt>d mod (q - 1)</tt> and <tt>q^(-1) mod p</tt>
  * respectively.
  */
diff --git a/ext/openssl/ossl_rand.c b/ext/openssl/ossl_rand.c
index 688c525a..c9585706 100644
--- a/ext/openssl/ossl_rand.c
+++ b/ext/openssl/ossl_rand.c
@@ -16,7 +16,7 @@ VALUE eRandomError;
  *  call-seq:
  *     seed(str) -> str
  *
- * ::seed is equivalent to ::add where +entropy+ is length of +str+.
+ * ::seed is equivalent to ::add where _entropy_ is length of _str_.
  */
 static VALUE
 ossl_rand_seed(VALUE self, VALUE str)
@@ -31,15 +31,15 @@ ossl_rand_seed(VALUE self, VALUE str)
  *  call-seq:
  *     add(str, entropy) -> self
  *
- * Mixes the bytes from +str+ into the Pseudo Random Number Generator(PRNG)
+ * 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
+ * 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.
+ * The _entropy_ argument is (the lower bound of) an estimate of how much
+ * randomness is contained in _str_, measured in bytes.
  *
  * === Example
  *
@@ -62,7 +62,7 @@ ossl_rand_add(VALUE self, VALUE str, VALUE entropy)
  *  call-seq:
  *     load_random_file(filename) -> true
  *
- * Reads bytes from +filename+ and adds them to the PRNG.
+ * Reads bytes from _filename_ and adds them to the PRNG.
  */
 static VALUE
 ossl_rand_load_file(VALUE self, VALUE filename)
@@ -79,7 +79,7 @@ ossl_rand_load_file(VALUE self, VALUE filename)
  *  call-seq:
  *     write_random_file(filename) -> true
  *
- * Writes a number of random generated bytes (currently 1024) to +filename+
+ * 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.
  */
@@ -98,7 +98,7 @@ ossl_rand_write_file(VALUE self, VALUE filename)
  *  call-seq:
  *	random_bytes(length) -> string
  *
- * Generates +string+ with +length+ number of cryptographically strong
+ * Generates a String with _length_ number of cryptographically strong
  * pseudo-random bytes.
  *
  * === Example
@@ -129,7 +129,7 @@ ossl_rand_bytes(VALUE self, VALUE len)
  *  call-seq:
  *	pseudo_bytes(length) -> string
  *
- * Generates +string+ with +length+ number of pseudo-random bytes.
+ * Generates a 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.
@@ -176,9 +176,9 @@ ossl_rand_egd(VALUE self, VALUE filename)
  *  call-seq:
  *     egd_bytes(filename, length) -> true
  *
- * Queries the entropy gathering daemon EGD on socket path given by +filename+.
+ * 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
+ * Fetches _length_ number of bytes and uses ::add to seed the OpenSSL built-in
  * PRNG.
  */
 static VALUE
@@ -199,7 +199,7 @@ ossl_rand_egd_bytes(VALUE self, VALUE filename, VALUE len)
  *  call-seq:
  *     status? => true | false
  *
- * Return true if the PRNG has been seeded with enough data, false otherwise.
+ * Return +true+ if the PRNG has been seeded with enough data, +false+ otherwise.
  */
 static VALUE
 ossl_rand_status(VALUE self)
diff --git a/ext/openssl/ossl_ssl.c b/ext/openssl/ossl_ssl.c
index 033e0346..4d674aa6 100644
--- a/ext/openssl/ossl_ssl.c
+++ b/ext/openssl/ossl_ssl.c
@@ -1186,7 +1186,7 @@ ossl_sslctx_set_security_level(VALUE self, VALUE value)
  *  call-seq:
  *     ctx.session_add(session) -> true | false
  *
- * Adds +session+ to the session cache.
+ * Adds _session_ to the session cache.
  */
 static VALUE
 ossl_sslctx_session_add(VALUE self, VALUE arg)
@@ -1204,7 +1204,7 @@ ossl_sslctx_session_add(VALUE self, VALUE arg)
  *  call-seq:
  *     ctx.session_remove(session) -> true | false
  *
- * Removes +session+ from the session cache.
+ * Removes _session_ from the session cache.
  */
 static VALUE
 ossl_sslctx_session_remove(VALUE self, VALUE arg)
@@ -1340,9 +1340,9 @@ ossl_sslctx_get_session_cache_stats(VALUE self)
 
 /*
  *  call-seq:
- *     ctx.flush_sessions(time | nil) -> self
+ *     ctx.flush_sessions(time) -> self
  *
- * Removes sessions in the internal cache that have expired at +time+.
+ * Removes sessions in the internal cache that have expired at _time_.
  */
 static VALUE
 ossl_sslctx_flush_sessions(int argc, VALUE *argv, VALUE self)
@@ -1404,10 +1404,10 @@ ossl_ssl_s_alloc(VALUE klass)
  *    SSLSocket.new(io) => aSSLSocket
  *    SSLSocket.new(io, ctx) => aSSLSocket
  *
- * Creates a new SSL socket from +io+ which must be a real IO object (not an
+ * Creates a new SSL socket from _io_ which must be a real IO object (not an
  * IO-like object that responds to read/write).
  *
- * If +ctx+ is provided the SSL Sockets initial params will be taken from
+ * If _ctx_ is provided the SSL Sockets initial params will be taken from
  * the context.
  *
  * The OpenSSL::Buffering module provides additional IO methods.
@@ -1757,7 +1757,7 @@ ossl_ssl_read_internal(int argc, VALUE *argv, VALUE self, int nonblock)
  *    ssl.sysread(length) => string
  *    ssl.sysread(length, buffer) => buffer
  *
- * Reads +length+ bytes from the SSL connection.  If a pre-allocated +buffer+
+ * Reads _length_ bytes from the SSL connection.  If a pre-allocated _buffer_
  * is provided the data will be written into it.
  */
 static VALUE
@@ -1776,7 +1776,7 @@ ossl_ssl_read(int argc, VALUE *argv, VALUE self)
  * block.  If "exception: false" is passed, this method returns a symbol of
  * :wait_readable, :wait_writable, or nil, rather than raising an exception.
  *
- * Reads +length+ bytes from the SSL connection.  If a pre-allocated +buffer+
+ * Reads _length_ bytes from the SSL connection.  If a pre-allocated _buffer_
  * is provided the data will be written into it.
  */
 static VALUE
@@ -1846,7 +1846,7 @@ ossl_ssl_write_internal(VALUE self, VALUE str, VALUE opts)
  * call-seq:
  *    ssl.syswrite(string) => Integer
  *
- * Writes +string+ to the SSL connection.
+ * Writes _string_ to the SSL connection.
  */
 static VALUE
 ossl_ssl_write(VALUE self, VALUE str)
@@ -1858,7 +1858,7 @@ ossl_ssl_write(VALUE self, VALUE str)
  * call-seq:
  *    ssl.syswrite_nonblock(string) => Integer
  *
- * Writes +string+ to the SSL connection in a non-blocking manner.  Raises an
+ * Writes _string_ to the SSL connection in a non-blocking manner.  Raises an
  * SSLError if writing would block.
  */
 static VALUE
@@ -2063,7 +2063,7 @@ ossl_ssl_pending(VALUE self)
  * call-seq:
  *    ssl.session_reused? -> true | false
  *
- * Returns true if a reused session was negotiated during the handshake.
+ * Returns +true+ if a reused session was negotiated during the handshake.
  */
 static VALUE
 ossl_ssl_session_reused(VALUE self)
@@ -2282,7 +2282,7 @@ Init_ossl_ssl(void)
      * This module contains configuration information about the SSL extension,
      * for example if socket support is enabled, or the host name TLS extension
      * is enabled.  Constants in this module will always be defined, but contain
-     * `true` or `false` values depending on the configuration of your OpenSSL
+     * +true+ or +false+ values depending on the configuration of your OpenSSL
      * installation.
      */
     mSSLExtConfig = rb_define_module_under(mOSSL, "ExtConfig");
@@ -2366,12 +2366,12 @@ Init_ossl_ssl(void)
      * A callback for additional certificate verification.  The callback is
      * invoked for each certificate in the chain.
      *
-     * The callback is invoked with two values.  +preverify_ok+ indicates
-     * indicates if the verification was passed (true) or not (false).
-     * +store_context+ is an OpenSSL::X509::StoreContext containing the
+     * The callback is invoked with two values.  _preverify_ok_ indicates
+     * indicates if the verification was passed (+true+) or not (+false+).
+     * _store_context_ is an OpenSSL::X509::StoreContext containing the
      * context used for certificate verification.
      *
-     * If the callback returns false, the chain verification is immediately
+     * If the callback returns +false+, the chain verification is immediately
      * stopped and a bad_certificate alert is then sent.
      */
     rb_attr(cSSLContext, rb_intern("verify_callback"), 1, 1, Qfalse);
@@ -2438,7 +2438,7 @@ Init_ossl_ssl(void)
     /*
      * A callback invoked when a new session was negotiated.
      *
-     * The callback is invoked with an SSLSocket.  If false is returned the
+     * The callback is invoked with an SSLSocket.  If +false+ is returned the
      * session will be removed from the internal cache.
      */
     rb_attr(cSSLContext, rb_intern("session_new_cb"), 1, 1, Qfalse);
diff --git a/ext/openssl/ossl_ssl_session.c b/ext/openssl/ossl_ssl_session.c
index fefbf28b..11287ad1 100644
--- a/ext/openssl/ossl_ssl_session.c
+++ b/ext/openssl/ossl_ssl_session.c
@@ -113,7 +113,7 @@ ossl_SSL_SESSION_cmp(const SSL_SESSION *a, const SSL_SESSION *b)
  * call-seq:
  *   session1 == session2 -> boolean
  *
- * Returns true if the two Session is the same, false if not.
+ * Returns +true+ if the two Session is the same, +false+ if not.
  */
 static VALUE ossl_ssl_session_eq(VALUE val1, VALUE val2)
 {
diff --git a/ext/openssl/ossl_x509cert.c b/ext/openssl/ossl_x509cert.c
index cecc3ca0..00bce40c 100644
--- a/ext/openssl/ossl_x509cert.c
+++ b/ext/openssl/ossl_x509cert.c
@@ -586,7 +586,8 @@ ossl_x509_sign(VALUE self, VALUE key, VALUE digest)
  * call-seq:
  *    cert.verify(key) => true | false
  *
- * Checks that cert signature is made with PRIVversion of this PUBLIC 'key'
+ * Verifies the signature of the certificate, with the public key _key_. _key_
+ * must be an instance of OpenSSL::PKey.
  */
 static VALUE
 ossl_x509_verify(VALUE self, VALUE key)
@@ -610,9 +611,10 @@ ossl_x509_verify(VALUE self, VALUE key)
 
 /*
  * call-seq:
- *    cert.check_private_key(key)
+ *    cert.check_private_key(key) -> true | false
  *
- * Checks if 'key' is PRIV key for this cert
+ * Returns +true+ if _key_ is the corresponding private key to the Subject
+ * Public Key Information, +false+ otherwise.
  */
 static VALUE
 ossl_x509_check_private_key(VALUE self, VALUE key)
diff --git a/ext/openssl/ossl_x509ext.c b/ext/openssl/ossl_x509ext.c
index b92b0786..ad810e4d 100644
--- a/ext/openssl/ossl_x509ext.c
+++ b/ext/openssl/ossl_x509ext.c
@@ -263,15 +263,15 @@ ossl_x509ext_alloc(VALUE klass)
 
 /*
  * call-seq:
- *    OpenSSL::X509::Extension.new asn1
- *    OpenSSL::X509::Extension.new name, value
- *    OpenSSL::X509::Extension.new name, value, critical
+ *    OpenSSL::X509::Extension.new(der)
+ *    OpenSSL::X509::Extension.new(oid, value)
+ *    OpenSSL::X509::Extension.new(oid, value, critical)
  *
  * Creates an X509 extension.
  *
- * The extension may be created from +asn1+ data or from an extension +name+
- * and +value+.  The +name+ may be either an OID or an extension name.  If
- * +critical+ is true the extension is marked critical.
+ * The extension may be created from _der_ data or from an extension _oid_
+ * and _value_.  The _oid_ may be either an OID or an extension name.  If
+ * _critical_ is +true+ the extension is marked critical.
  */
 static VALUE
 ossl_x509ext_initialize(int argc, VALUE *argv, VALUE self)
diff --git a/ext/openssl/ossl_x509name.c b/ext/openssl/ossl_x509name.c
index a10ae2c3..20f811ea 100644
--- a/ext/openssl/ossl_x509name.c
+++ b/ext/openssl/ossl_x509name.c
@@ -135,15 +135,15 @@ ossl_x509name_init_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, args))
  *
  * Creates a new Name.
  *
- * A name may be created from a DER encoded string +der+, an Array
- * representing a +distinguished_name+ or a +distinguished_name+ along with a
- * +template+.
+ * A name may be created from a DER encoded string _der_, an Array
+ * representing a _distinguished_name_ or a _distinguished_name_ along with a
+ * _template_.
  *
  *   name = OpenSSL::X509::Name.new [['CN', 'nobody'], ['DC', 'example']]
  *
  *   name = OpenSSL::X509::Name.new name.to_der
  *
- * See add_entry for a description of the +distinguished_name+ Array's
+ * See add_entry for a description of the _distinguished_name_ Array's
  * contents
  */
 static VALUE
@@ -204,7 +204,7 @@ ossl_x509name_initialize_copy(VALUE self, VALUE other)
  * call-seq:
  *    name.add_entry(oid, value [, type]) => self
  *
- * Adds a new entry with the given +oid+ and +value+ to this name.  The +oid+
+ * Adds a new entry with the given _oid_ and _value_ to this name.  The _oid_
  * is an object identifier defined in ASN.1.  Some common OIDs are:
  *
  * C::  Country Name
@@ -251,15 +251,19 @@ ossl_x509name_to_s_old(VALUE self)
 
 /*
  * call-seq:
- *    name.to_s => string
- *    name.to_s(flags) => string
+ *    name.to_s         -> string
+ *    name.to_s(format) -> string
  *
- * Returns this name as a Distinguished Name string.  +flags+ may be one of:
+ * Returns a String representation of the Distinguished Name. _format_ is
+ * one of:
  *
  * * OpenSSL::X509::Name::COMPAT
  * * OpenSSL::X509::Name::RFC2253
  * * OpenSSL::X509::Name::ONELINE
  * * OpenSSL::X509::Name::MULTILINE
+ *
+ * If _format_ is omitted, the largely broken and traditional OpenSSL format
+ * is used.
  */
 static VALUE
 ossl_x509name_to_s(int argc, VALUE *argv, VALUE self)
@@ -345,11 +349,11 @@ ossl_x509name_cmp0(VALUE self, VALUE other)
 
 /*
  * call-seq:
- *    name.cmp other => integer
- *    name.<=> other => integer
+ *    name.cmp(other) -> -1 | 0 | 1
+ *    name <=> other  -> -1 | 0 | 1
  *
- * Compares this Name with +other+ and returns 0 if they are the same and -1 or
- * +1 if they are greater or less than each other respectively.
+ * Compares this Name with _other_ and returns +0+ if they are the same and +-1+
+ * or ++1+ if they are greater or less than each other respectively.
  */
 static VALUE
 ossl_x509name_cmp(VALUE self, VALUE other)
@@ -365,9 +369,9 @@ ossl_x509name_cmp(VALUE self, VALUE other)
 
 /*
  * call-seq:
- *   name.eql? other => boolean
+ *   name.eql?(other) -> true | false
  *
- * Returns true if +name+ and +other+ refer to the same hash key.
+ * Returns true if _name_ and _other_ refer to the same hash key.
  */
 static VALUE
 ossl_x509name_eql(VALUE self, VALUE other)
diff --git a/ext/openssl/ossl_x509store.c b/ext/openssl/ossl_x509store.c
index eb81e0d4..3ea6ea14 100644
--- a/ext/openssl/ossl_x509store.c
+++ b/ext/openssl/ossl_x509store.c
@@ -242,9 +242,9 @@ ossl_x509store_initialize(int argc, VALUE *argv, VALUE self)
 
 /*
  * call-seq:
- *   store.flags = flag
+ *   store.flags = flags
  *
- * Sets +flag+ to the Store. +flag+ consists of zero or more of the constants
+ * Sets _flags_ to the Store. _flags_ consists of zero or more of the constants
  * defined in with name V_FLAG_* or'ed together.
  */
 static VALUE
@@ -263,7 +263,7 @@ ossl_x509store_set_flags(VALUE self, VALUE flags)
  * call-seq:
  *   store.purpose = purpose
  *
- * Sets the store's purpose to +purpose+. If specified, the verifications on
+ * Sets the store's purpose to _purpose_. If specified, the verifications on
  * the store will check every untrusted certificate's extensions are consistent
  * with the purpose. The purpose is specified by constants:
  *
@@ -322,8 +322,9 @@ ossl_x509store_set_time(VALUE self, VALUE time)
  * call-seq:
  *   store.add_file(file) -> self
  *
- * Adds the certificates in +file+ to the certificate store.  The +file+ can
- * contain multiple PEM-encoded certificates.
+ * Adds the certificates in _file_ to the certificate store. _file_ is the path
+ * to the file, and the file contains one or more certificates in PEM format
+ * concatenated together.
  */
 static VALUE
 ossl_x509store_add_file(VALUE self, VALUE file)
@@ -350,7 +351,7 @@ ossl_x509store_add_file(VALUE self, VALUE file)
  * call-seq:
  *   store.add_path(path) -> self
  *
- * Adds +path+ as the hash dir to be looked up by the store.
+ * Adds _path_ as the hash dir to be looked up by the store.
  */
 static VALUE
 ossl_x509store_add_path(VALUE self, VALUE dir)
@@ -377,7 +378,7 @@ ossl_x509store_add_path(VALUE self, VALUE dir)
  * call-seq:
  *   store.set_default_paths
  *
- * Configures +store+ to look up CA certificates from the system default
+ * Configures _store_ to look up CA certificates from the system default
  * certificate store as needed basis. The location of the store can usually be
  * determined by:
  *
@@ -401,7 +402,7 @@ ossl_x509store_set_default_paths(VALUE self)
  * call-seq:
  *   store.add_cert(cert)
  *
- * Adds the OpenSSL::X509::Certificate +cert+ to the certificate store.
+ * Adds the OpenSSL::X509::Certificate _cert_ to the certificate store.
  */
 static VALUE
 ossl_x509store_add_cert(VALUE self, VALUE arg)
@@ -422,7 +423,7 @@ ossl_x509store_add_cert(VALUE self, VALUE arg)
  * call-seq:
  *   store.add_crl(crl) -> self
  *
- * Adds the OpenSSL::X509::CRL +crl+ to the store.
+ * Adds the OpenSSL::X509::CRL _crl_ to the store.
  */
 static VALUE
 ossl_x509store_add_crl(VALUE self, VALUE arg)
@@ -447,15 +448,15 @@ static VALUE ossl_x509stctx_get_chain(VALUE);
  * call-seq:
  *   store.verify(cert, chain = nil) -> true | false
  *
- * Performs a certificate verification on the OpenSSL::X509::Certificate +cert+.
+ * Performs a certificate verification on the OpenSSL::X509::Certificate _cert_.
  *
- * +chain+ can be an array of OpenSSL::X509::Certificate that is used to
+ * _chain_ can be an array of OpenSSL::X509::Certificate that is used to
  * construct the certificate chain.
  *
  * If a block is given, it overrides the callback set by #verify_callback=.
  *
  * After finishing the verification, the error information can be retrieved by
- * #error, #error_string, and the resuting complete certificate chain can be
+ * #error, #error_string, and the resulting complete certificate chain can be
  * retrieved by #chain.
  */
 static VALUE
diff --git a/lib/openssl/buffering.rb b/lib/openssl/buffering.rb
index d773637c..8b5dd9da 100644
--- a/lib/openssl/buffering.rb
+++ b/lib/openssl/buffering.rb
@@ -63,7 +63,7 @@ module OpenSSL::Buffering
   end
 
   ##
-  # Consumes +size+ bytes from the buffer
+  # Consumes _size_ bytes from the buffer
 
   def consume_rbuff(size=nil)
     if @rbuffer.empty?
@@ -79,7 +79,7 @@ module OpenSSL::Buffering
   public
 
   ##
-  # Reads +size+ bytes from the stream.  If +buf+ is provided it must
+  # Reads _size_ bytes from the stream.  If _buf_ is provided it must
   # reference a string which will receive the data.
   #
   # See IO#read for full details.
@@ -106,7 +106,7 @@ module OpenSSL::Buffering
   end
 
   ##
-  # Reads at most +maxlen+ bytes from the stream.  If +buf+ is provided it
+  # Reads at most _maxlen_ bytes from the stream.  If _buf_ is provided it
   # must reference a string which will receive the data.
   #
   # See IO#readpartial for full details.
@@ -136,7 +136,7 @@ module OpenSSL::Buffering
   end
 
   ##
-  # Reads at most +maxlen+ bytes in the non-blocking manner.
+  # Reads at most _maxlen_ bytes in the non-blocking manner.
   #
   # When no data can be read without blocking it raises
   # OpenSSL::SSL::SSLError extended by IO::WaitReadable or IO::WaitWritable.
@@ -190,11 +190,11 @@ module OpenSSL::Buffering
   end
 
   ##
-  # Reads the next "line" from the stream.  Lines are separated by +eol+.  If
-  # +limit+ is provided the result will not be longer than the given number of
+  # Reads the next "line" from the stream.  Lines are separated by _eol_.  If
+  # _limit_ is provided the result will not be longer than the given number of
   # bytes.
   #
-  # +eol+ may be a String or Regexp.
+  # _eol_ may be a String or Regexp.
   #
   # Unlike IO#gets the line read will not be assigned to +$_+.
   #
@@ -220,7 +220,7 @@ module OpenSSL::Buffering
 
   ##
   # Executes the block for every line in the stream where lines are separated
-  # by +eol+.
+  # by _eol_.
   #
   # See also #gets
 
@@ -232,7 +232,7 @@ module OpenSSL::Buffering
   alias each_line each
 
   ##
-  # Reads lines from the stream which are separated by +eol+.
+  # Reads lines from the stream which are separated by _eol_.
   #
   # See also #gets
 
@@ -245,7 +245,7 @@ module OpenSSL::Buffering
   end
 
   ##
-  # Reads a line from the stream which is separated by +eol+.
+  # Reads a line from the stream which is separated by _eol_.
   #
   # Raises EOFError if at end of file.
 
@@ -281,7 +281,7 @@ module OpenSSL::Buffering
   end
 
   ##
-  # Pushes character +c+ back onto the stream such that a subsequent buffered
+  # Pushes character _c_ back onto the stream such that a subsequent buffered
   # character read will return it.
   #
   # Unlike IO#getc multiple bytes may be pushed back onto the stream.
@@ -308,7 +308,7 @@ module OpenSSL::Buffering
   private
 
   ##
-  # Writes +s+ to the buffer.  When the buffer is full or #sync is true the
+  # Writes _s_ to the buffer.  When the buffer is full or #sync is true the
   # buffer is flushed to the underlying socket.
 
   def do_write(s)
@@ -336,8 +336,8 @@ module OpenSSL::Buffering
   public
 
   ##
-  # Writes +s+ to the stream.  If the argument is not a string it will be
-  # converted using String#to_s.  Returns the number of bytes written.
+  # Writes _s_ to the stream.  If the argument is not a String it will be
+  # converted using +.to_s+ method.  Returns the number of bytes written.
 
   def write(s)
     do_write(s)
@@ -345,7 +345,7 @@ module OpenSSL::Buffering
   end
 
   ##
-  # Writes +s+ in the non-blocking manner.
+  # Writes _s_ in the non-blocking manner.
   #
   # If there is buffered data, it is flushed first.  This may block.
   #
@@ -387,8 +387,8 @@ module OpenSSL::Buffering
   end
 
   ##
-  # Writes +s+ to the stream.  +s+ will be converted to a String using
-  # String#to_s.
+  # Writes _s_ to the stream.  _s_ will be converted to a String using
+  # +.to_s+ method.
 
   def <<(s)
     do_write(s)
@@ -396,7 +396,7 @@ module OpenSSL::Buffering
   end
 
   ##
-  # Writes +args+ to the stream along with a record separator.
+  # Writes _args_ to the stream along with a record separator.
   #
   # See IO#puts for full details.
 
@@ -416,7 +416,7 @@ module OpenSSL::Buffering
   end
 
   ##
-  # Writes +args+ to the stream.
+  # Writes _args_ to the stream.
   #
   # See IO#print for full details.
 
diff --git a/lib/openssl/config.rb b/lib/openssl/config.rb
index 88225451..48d8be00 100644
--- a/lib/openssl/config.rb
+++ b/lib/openssl/config.rb
@@ -30,7 +30,8 @@ module OpenSSL
     class << self
 
       ##
-      # Parses a given +string+ as a blob that contains configuration for openssl.
+      # Parses a given _string_ as a blob that contains configuration for
+      # OpenSSL.
       #
       # If the source of the IO is a file, then consider using #parse_config.
       def parse(string)
@@ -46,7 +47,7 @@ module OpenSSL
       alias load new
 
       ##
-      # Parses the configuration data read from +io+, see also #parse.
+      # Parses the configuration data read from _io_, see also #parse.
       #
       # Raises a ConfigError on invalid configuration data.
       def parse_config(io)
@@ -236,7 +237,7 @@ module OpenSSL
     #
     # This can be used in contexts like OpenSSL::X509::ExtensionFactory.config=
     #
-    # If the optional +filename+ parameter is provided, then it is read in and
+    # If the optional _filename_ parameter is provided, then it is read in and
     # parsed via #parse_config.
     #
     # This can raise IO exceptions based on the access, or availability of the
@@ -255,7 +256,7 @@ module OpenSSL
     end
 
     ##
-    # Gets the value of +key+ from the given +section+
+    # Gets the value of _key_ from the given _section_
     #
     # Given the following configurating file being loaded:
     #
@@ -265,8 +266,8 @@ module OpenSSL
     #     #=> [ default ]
     #     #   foo=bar
     #
-    # You can get a specific value from the config if you know the +section+
-    # and +key+ like so:
+    # You can get a specific value from the config if you know the _section_
+    # and _key_ like so:
     #
     #   config.get_value('default','foo')
     #     #=> "bar"
@@ -297,7 +298,7 @@ module OpenSSL
     end
 
     ##
-    # Set the target +key+ with a given +value+ under a specific +section+.
+    # Set the target _key_ with a given _value_ under a specific _section_.
     #
     # Given the following configurating file being loaded:
     #
@@ -307,7 +308,7 @@ module OpenSSL
     #     #=> [ default ]
     #     #   foo=bar
     #
-    # You can set the value of +foo+ under the +default+ section to a new
+    # You can set the value of _foo_ under the _default_ section to a new
     # value:
     #
     #   config.add_value('default', 'foo', 'buzz')
@@ -322,7 +323,7 @@ module OpenSSL
     end
 
     ##
-    # Get a specific +section+ from the current configuration
+    # Get a specific _section_ from the current configuration
     #
     # Given the following configurating file being loaded:
     #
@@ -351,7 +352,7 @@ module OpenSSL
     end
 
     ##
-    # Sets a specific +section+ name with a Hash +pairs+
+    # Sets a specific _section_ name with a Hash _pairs_.
     #
     # Given the following configuration being created:
     #
@@ -365,7 +366,7 @@ module OpenSSL
     #     #   baz=buz
     #
     # It's important to note that this will essentially merge any of the keys
-    # in +pairs+ with the existing +section+. For example:
+    # in _pairs_ with the existing _section_. For example:
     #
     #   config['default']
     #     #=> {"foo"=>"bar", "baz"=>"buz"}
diff --git a/lib/openssl/digest.rb b/lib/openssl/digest.rb
index b5729240..b6744de6 100644
--- a/lib/openssl/digest.rb
+++ b/lib/openssl/digest.rb
@@ -20,7 +20,7 @@ module OpenSSL
       alg += %w(DSS DSS1 SHA)
     end
 
-    # Return the +data+ hash computed with +name+ Digest. +name+ is either the
+    # Return the hash value computed with _name_ Digest. _name_ is either the
     # long name or short name of a supported digest algorithm.
     #
     # === Examples
@@ -56,7 +56,7 @@ module OpenSSL
 
   end # Digest
 
-  # Returns a Digest subclass by +name+.
+  # Returns a Digest subclass by _name_
   #
   #   require 'openssl'
   #
diff --git a/lib/openssl/ssl.rb b/lib/openssl/ssl.rb
index 4ea0ffaf..ced46b0d 100644
--- a/lib/openssl/ssl.rb
+++ b/lib/openssl/ssl.rb
@@ -139,8 +139,8 @@ YoaOffgTf5qxiwkjnlVZQc3whgnEt9FpVMvQ9eknyeGB5KHfayAc3+hUAvI3/Cr3
       #
       # Sets saner defaults optimized for the use with HTTP-like protocols.
       #
-      # If a Hash +params+ is given, the parameters are overridden with it.
-      # The keys in +params+ must be assignment methods on SSLContext.
+      # If a Hash _params_ is given, the parameters are overridden with it.
+      # The keys in _params_ must be assignment methods on SSLContext.
       #
       # If the verify_mode is not VERIFY_NONE and ca_file, ca_path and
       # cert_store are not set then the system default certificate store is
@@ -372,8 +372,8 @@ YoaOffgTf5qxiwkjnlVZQc3whgnEt9FpVMvQ9eknyeGB5KHfayAc3+hUAvI3/Cr3
       attr_accessor :start_immediately
 
       # Creates a new instance of SSLServer.
-      # * +srv+ is an instance of TCPServer.
-      # * +ctx+ is an instance of OpenSSL::SSL::SSLContext.
+      # * _srv_ is an instance of TCPServer.
+      # * _ctx_ is an instance of OpenSSL::SSL::SSLContext.
       def initialize(svr, ctx)
         @svr = svr
         @ctx = ctx