* 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
2011-05-16 21:51:12 +00:00 · 2011-05-16 21:51:12 +00:00 · 61a5a6393d
--- a/ext/openssl/ossl_asn1.c
+++ b/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.
-     * But opposed to the time when an ASN.1 type is to be encoded, when
-     * parsing them it is not possible to deduce the "real type" of tagged
+     * type (e.g. INTEGER, OCTET STRING etc.) this value has, regardless
+     * of its tagging.
+     * 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
-     * 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.      * Primitive values can never be infinite length encodings, thus it is not
+     * 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
     * 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
-     * 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.
+     * for ASN1Data, with the addition of +tagging+.
     *
     * == 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);