Merge pull request #970 from rhenium/ky/ts-factory-attr-docs

ts: fix docs for attrs on OpenSSL::Timestamp::Factory

Author: rhenium

ext/openssl/ossl_ts.c

@@ -1511,65 +1511,39 @@ Init_ossl_ts(void)
      *      fac.default_policy_id = '1.2.3.4.5'
      *      fac.additional_certificates = [ inter1, inter2 ]
      *      timestamp = fac.create_timestamp(p12.key, p12.certificate, req)
-     *
-     * ==Attributes
-     *
-     * ===default_policy_id
+     */
+    cTimestampFactory = rb_define_class_under(mTimestamp, "Factory", rb_cObject);
+    /*
+     * The list of digest algorithms that the factory is allowed
+     * create timestamps for. Known vulnerable or weak algorithms should not be
+     * allowed where possible. Must be an Array of String or OpenSSL::Digest
+     * subclass instances.
+     */
+    rb_attr(cTimestampFactory, rb_intern_const("allowed_digests"), 1, 1, 0);
+    /*
+     * A String representing the default policy object identifier, or +nil+.
      *
      * Request#policy_id will always be preferred over this if present in the
-     * Request, only if Request#policy_id is nil default_policy will be used.
+     * Request, only if Request#policy_id is +nil+ default_policy will be used.
      * If none of both is present, a TimestampError will be raised when trying
      * to create a Response.
-     *
-     * call-seq:
-     *       factory.default_policy_id = "string" -> string
-     *       factory.default_policy_id            -> string or nil
-     *
-     * ===serial_number
-     *
-     * Sets or retrieves the serial number to be used for timestamp creation.
-     * Must be present for timestamp creation.
-     *
-     * call-seq:
-     *       factory.serial_number = number -> number
-     *       factory.serial_number          -> number or nil
-     *
-     * ===gen_time
-     *
-     * Sets or retrieves the Time value to be used in the Response. Must be
-     * present for timestamp creation.
-     *
-     * call-seq:
-     *       factory.gen_time = Time -> Time
-     *       factory.gen_time        -> Time or nil
-     *
-     * ===additional_certs
-     *
-     * Sets or retrieves additional certificates apart from the timestamp
-     * certificate (e.g. intermediate certificates) to be added to the Response.
-     * Must be an Array of OpenSSL::X509::Certificate.
-     *
-     * call-seq:
-     *       factory.additional_certs = [cert1, cert2] -> [ cert1, cert2 ]
-     *       factory.additional_certs                  -> array or nil
-     *
-     * ===allowed_digests
-     *
-     * Sets or retrieves the digest algorithms that the factory is allowed
-     * create timestamps for. Known vulnerable or weak algorithms should not be
-     * allowed where possible.
-     * Must be an Array of String or OpenSSL::Digest subclass instances.
-     *
-     * call-seq:
-     *       factory.allowed_digests = ["sha1", OpenSSL::Digest.new('SHA256').new] -> [ "sha1", OpenSSL::Digest) ]
-     *       factory.allowed_digests                                               -> array or nil
-     *
      */
-    cTimestampFactory = rb_define_class_under(mTimestamp, "Factory", rb_cObject);
-    rb_attr(cTimestampFactory, rb_intern_const("allowed_digests"), 1, 1, 0);
     rb_attr(cTimestampFactory, rb_intern_const("default_policy_id"), 1, 1, 0);
+    /*
+     * The serial number to be used for timestamp creation. Must be present for
+     * timestamp creation. Must be an instance of OpenSSL::BN or Integer.
+     */
     rb_attr(cTimestampFactory, rb_intern_const("serial_number"), 1, 1, 0);
+    /*
+     * The Time value to be used in the Response. Must be present for timestamp
+     * creation.
+     */
     rb_attr(cTimestampFactory, rb_intern_const("gen_time"), 1, 1, 0);
+    /*
+     * Additional certificates apart from the timestamp certificate (e.g.
+     * intermediate certificates) to be added to the Response.
+     * Must be an Array of OpenSSL::X509::Certificate, or +nil+.
+     */
     rb_attr(cTimestampFactory, rb_intern_const("additional_certs"), 1, 1, 0);
     rb_define_method(cTimestampFactory, "create_timestamp", ossl_tsfac_create_ts, 3);
 }