* ext/openssl/ossl_asn1.c: Fix more typos. Document attributes

explicitly. Set indentation for verbose sections from 4 to 2
  spaces.


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

ext/openssl/ossl_asn1.c

@@ -661,8 +661,10 @@ ossl_asn1_class2sym(int tc)
  *
  * +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_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
@@ -978,11 +980,14 @@ ossl_asn1_decode_all(VALUE self, VALUE obj)
  *    OpenSSL::ASN1::Primitive.new( value [, tag, tagging, tag_class ]) => Primitive
  *
  * +value+: is mandatory.
+ *
  * +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
  * 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
  * +:CONTEXT_SPECIFIC+ is used as the default. For possible values please
@@ -1358,9 +1363,9 @@ Init_ossl_asn1()
      * instances of a corresponding sub-class of Primitive or they are
      * instances of ASN1Data if the value was tagged implicitly or explicitly.
      * Please cf. Primitive documentation for details on sub-classes and
-     * their respective mappings of ASN.1 data types to Ruby types.
+     * their respective mappings of ASN.1 data types to Ruby objects.
      *
-     * == Possible values for attribute +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.
@@ -1455,53 +1460,20 @@ Init_ossl_asn1()
     /* Document-class: OpenSSL::ASN1::ASN1Data
      *
      * The top-level class representing any ASN.1 object. When parsed by
-     * ASN1#decode, tagged values are always represented by an instance
+     * ASN1.decode, tagged values are always represented by an instance
      * of ASN1Data.
      *
-     * == Attributes
-     *
-     * === +value+
-     *
-     * Carries the value of a ASN.1 type.
-     * Please confer Constructive and Primitive for the mappings between
-     * ASN.1 data types and Ruby classes.
-     *
-     * === +tag+
-     *
-     * A +Number+ representing the tag number of this ASN1Data. Never +nil+.
-     *
-     * === +tag_class+
-     *
-     * A +Symbol+ representing the tag class of this ASN1Data. Never +nil+.
-     * See ASN1Data for possible values.
-     *
-     * === +infinite_length+
-     *
-     * Never +nil+. A Boolean 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
-     * scenarios where large amounts of data need to be transferred it
-     * might be desirable to have some kind of streaming support available.
-     * For example, huge OCTET STRINGs are preferably sent in smaller-sized
-     * chunks, each at a time.
-     * This is possible in BER by setting the length bytes of an encoding
-     * to zero and by this indicating that the following value will be
-     * sent in chunks. Infinite length encodings are always constructed.
-     * The end of such a stream of chunks is indicated by sending a EOC
-     * (End of Content) tag. SETs and SEQUENCEs may use an infinite length
-     * encoding, but also primitive types such as e.g. OCTET STRINGS or
-     * BIT STRINGS may leverage this functionality (cf. ITU-T X.690).
-     *
      * == The role of ASN1Data for parsing tagged values
      *
      * When encoding an ASN.1 type it is inherently clear what original
-     * type a this value has, regardless of its tagging.
+     * type (e.g. INTEGER, OCTET STRING etc.) this value has, regardless
-     * But opposed to the time when an ASN.1 type is to be encoded, when
+     * of its tagging.
-     * parsing them it is not possible to deduce the "real type" of tagged
+     * But opposed to the time an ASN.1 type is to be encoded, when parsing
+     * them it is not possible to deduce the "real type" of tagged
      * values. This is why tagged values are generally parsed into ASN1Data
      * instances, but with a different outcome for implicit and explicit
      * tagging.
+     *
      * === Example of a parsed implicitly tagged value
      *
      * An implicitly 1-tagged INTEGER value will be parsed as an
@@ -1573,9 +1545,38 @@ Init_ossl_asn1()
      *   puts int2.value # => 1
      */
     cASN1Data = rb_define_class_under(mASN1, "ASN1Data", rb_cObject);
+    /*
+     * Carries the value of a ASN.1 type.
+     * Please confer Constructive and Primitive for the mappings between
+     * ASN.1 data types and Ruby classes.
+     */
     rb_attr(cASN1Data, rb_intern("value"), 1, 1, 0);
+    /*
+     * A +Number+ 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+.
+     * 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
+     * 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
+     * scenarios where large amounts of data need to be transferred it
+     * might be desirable to have some kind of streaming support available.
+     * For example, huge OCTET STRINGs are preferably sent in smaller-sized
+     * chunks, each at a time.
+     * This is possible in BER by setting the length bytes of an encoding
+     * to zero and by this indicating that the following value will be
+     * sent in chunks. Infinite length encodings are always constructed.
+     * The end of such a stream of chunks is indicated by sending a EOC
+     * (End of Content) tag. SETs and SEQUENCEs may use an infinite length
+     * encoding, but also primitive types such as e.g. OCTET STRINGS or
+     * BIT STRINGS may leverage this functionality (cf. ITU-T X.690).
+     */
     rb_attr(cASN1Data, rb_intern("infinite_length"), 1, 1, 0);
     rb_define_method(cASN1Data, "initialize", ossl_asn1data_initialize, 3);
     rb_define_method(cASN1Data, "to_der", ossl_asn1data_to_der, 0);
@@ -1583,11 +1584,8 @@ Init_ossl_asn1()
     /* Document-class: OpenSSL::ASN1::Primitive
      *
      * The parent class for all primitive encodings. Attributes are the same as
-     * for ASN1Data, with the addition of +tagging+. +tagging+ may be used
+     * for ASN1Data, with the addition of +tagging+. 
-     * as a hint for encoding a value either implicitly or explicitly by
+     * Primitive values can never be infinite length encodings, thus it is not
-     * setting it either to +:IMPLICIT+ or to +:EXPLICIT+.
-     * +tagging+ is not set when a ASN.1 structure is parsed using
-     * OpenSSL::ASN1.decode.      * Primitive values can never be infinite length encodings, thus it is not
      * possible to set the +infinite_length+ attribute for Primitive and its
      * sub-classes.
      *
@@ -1633,7 +1631,7 @@ Init_ossl_asn1()
      *
      * == Examples
      * With the Exception of OpenSSL::ASN1::EndOfContent, each Primitive class
-     * takes at least one parameter, the +value+.
+     * constructor takes at least one parameter, the +value+.
      *
      * === Creating EndOfContent
      *   eoc = OpenSSL::ASN1::EndOfContent.new
@@ -1644,6 +1642,12 @@ Init_ossl_asn1()
      *   prim_zero_tagged_explicit = <class>.new(value, 0, :EXPLICIT)
      */
     cASN1Primitive = rb_define_class_under(mASN1, "Primitive", cASN1Data);
+    /*
+     * 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
+     * OpenSSL::ASN1.decode.
+     */
     rb_attr(cASN1Primitive, rb_intern("tagging"), 1, 1, Qtrue);
     rb_undef_method(cASN1Primitive, "infinite_length=");
     rb_define_method(cASN1Primitive, "initialize", ossl_asn1_initialize, -1);
@@ -1653,11 +1657,7 @@ Init_ossl_asn1()
      *
      * 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+. +tagging+ may be used
+     * for ASN1Data, with the addition of +tagging+.
-     * as a hint for encoding to encode 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
-     * OpenSSL::ASN1.decode.
      *
      * == SET and SEQUENCE
      *
@@ -1713,6 +1713,12 @@ Init_ossl_asn1()
      */
     cASN1Constructive = rb_define_class_under(mASN1,"Constructive", cASN1Data);
     rb_include_module(cASN1Constructive, rb_mEnumerable);
+    /*
+     * 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
+     * OpenSSL::ASN1.decode.
+     */
     rb_attr(cASN1Constructive, rb_intern("tagging"), 1, 1, Qtrue);
     rb_define_method(cASN1Constructive, "initialize", ossl_asn1_initialize, -1);
     rb_define_method(cASN1Constructive, "to_der", ossl_asn1cons_to_der, 0);