include: make docs more consistent

Like upstream bitcoin-core/secp256k1#1476 .
real-or-random · Jan 23, 2024 · 010f1fe · 010f1fe
1 parent 7abf319
commit 010f1fe
Show file tree

Hide file tree

Showing 5 changed files with 49 additions and 50 deletions.
diff --git a/include/secp256k1_ecdsa_adaptor.h b/include/secp256k1_ecdsa_adaptor.h
@@ -71,7 +71,7 @@ SECP256K1_API const secp256k1_nonce_function_hardened_ecdsa_adaptor secp256k1_no
  *  this file and applied the suggested countermeasures.
  *
  *  Returns: 1 on success, 0 on failure
- *  Args:             ctx: a secp256k1 context object (not secp256k1_context_static)
+ *  Args:             ctx: pointer to a context object (not secp256k1_context_static)
  *  Out:   adaptor_sig162: pointer to 162 byte to store the returned signature
  *  In:          seckey32: pointer to 32 byte secret key that will be used for
  *                         signing
@@ -101,7 +101,7 @@ SECP256K1_API int secp256k1_ecdsa_adaptor_encrypt(
  *  and the completed ECDSA signature.
  *
  *  Returns: 1 on success, 0 on failure
- *  Args:            ctx: a secp256k1 context object
+ *  Args:            ctx: pointer to a context object
  *  In:   adaptor_sig162: pointer to 162-byte signature to verify
  *                pubkey: pointer to the public key corresponding to the secret key
  *                        used for signing
@@ -121,7 +121,7 @@ SECP256K1_API int secp256k1_ecdsa_adaptor_verify(
  *  Derives an ECDSA signature from an adaptor signature and an adaptor decryption key.
  *
  *  Returns: 1 on success, 0 on failure
- *  Args:              ctx: a secp256k1 context object
+ *  Args:              ctx: pointer to a context object
  *  Out:               sig: pointer to the ECDSA signature to create
  *  In:           deckey32: pointer to 32-byte decryption secret key for the adaptor
  *                          encryption public key
@@ -140,7 +140,7 @@ SECP256K1_API int secp256k1_ecdsa_adaptor_decrypt(
  *  signature.
  *
  *  Returns: 1 on success, 0 on failure
- *  Args:             ctx: a secp256k1 context object (not secp256k1_context_static)
+ *  Args:             ctx: pointer to a context object (not secp256k1_context_static)
  *  Out:         deckey32: pointer to 32-byte adaptor decryption key for the adaptor
  *                         encryption public key
  *  In:               sig: pointer to ECDSA signature to recover the adaptor decryption

diff --git a/include/secp256k1_ecdsa_s2c.h b/include/secp256k1_ecdsa_s2c.h
@@ -33,7 +33,7 @@ typedef struct {
  *
  *  Returns: 1 if the opening could be parsed
  *           0 if the opening could not be parsed
- *  Args:    ctx: a secp256k1 context object.
+ *  Args:    ctx: pointer to a context object
  *  Out: opening: pointer to an opening object. If 1 is returned, it is set to a
  *                parsed version of input. If not, its value is unspecified.
  *  In:  input33: pointer to 33-byte array with a serialized opening
@@ -49,9 +49,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_s2c_opening_parse
  *
  *  Returns: 1 if the opening was successfully serialized.
  *           0 if the opening could not be serialized
- *  Args:     ctx: a secp256k1 context object
+ *  Args:     ctx: pointer to a context object
  *  Out: output33: pointer to a 33-byte array to place the serialized opening in
- *  In:   opening: a pointer to an initialized `secp256k1_ecdsa_s2c_opening`
+ *  In:   opening: pointer to an initialized `secp256k1_ecdsa_s2c_opening`
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_s2c_opening_serialize(
     const secp256k1_context *ctx,
@@ -63,9 +63,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_s2c_opening_seria
  *
  *  Returns: 1: signature created
  *           0: the nonce generation function failed, or the private key was invalid.
- *  Args:    ctx:  pointer to a context object (not secp256k1_context_static)
- *  Out:     sig:  pointer to an array where the signature will be placed (cannot be NULL)
- *   s2c_opening:  if non-NULL, pointer to an secp256k1_ecdsa_s2c_opening structure to populate
+ *  Args:    ctx: pointer to a context object (not secp256k1_context_static)
+ *  Out:     sig: pointer to an array where the signature will be placed (cannot be NULL)
+ *   s2c_opening: if non-NULL, pointer to an secp256k1_ecdsa_s2c_opening structure to populate
  *  In:    msg32: the 32-byte message hash being signed (cannot be NULL)
  *        seckey: pointer to a 32-byte secret key (cannot be NULL)
  *    s2c_data32: pointer to a 32-byte data to commit to in the nonce (cannot be NULL)
@@ -84,7 +84,7 @@ SECP256K1_API int secp256k1_ecdsa_s2c_sign(
  *  Returns: 1: the signature contains a commitment to data32 (though it does
  *              not necessarily need to be a valid siganture!)
  *           0: incorrect opening
- *  Args:    ctx: a secp256k1 context object
+ *  Args:    ctx: pointer to a context object
  *  In:      sig: the signature containing the sign-to-contract commitment (cannot be NULL)
  *        data32: the 32-byte data that was committed to (cannot be NULL)
  *       opening: pointer to the opening created during signing (cannot be NULL)
@@ -193,8 +193,8 @@ SECP256K1_API int secp256k1_ecdsa_anti_exfil_signer_commit(
  *
  *  Returns: 1: signature created
  *           0: the nonce generation function failed, or the private key was invalid.
- *  Args:    ctx:  pointer to a context object (not secp256k1_context_static)
- *  Out:     sig:  pointer to an array where the signature will be placed (cannot be NULL)
+ *  Args:    ctx: pointer to a context object (not secp256k1_context_static)
+ *  Out:     sig: pointer to an array where the signature will be placed (cannot be NULL)
  *  In:    msg32: the 32-byte message hash being signed (cannot be NULL)
  *        seckey: pointer to a 32-byte secret key (cannot be NULL)
  *   host_data32: pointer to 32-byte host-provided randomness (cannot be NULL)
@@ -211,7 +211,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_anti_exfil_sign(
  *
  *  Returns: 1: the signature is valid and contains a commitment to host_data32
  *           0: incorrect opening
- *  Args:    ctx: a secp256k1 context object
+ *  Args:    ctx: pointer to a context object
  *  In:      sig: the signature produced by the signer (cannot be NULL)
  *     msghash32: the 32-byte message hash being verified (cannot be NULL)
  *        pubkey: pointer to the signer's public key (cannot be NULL)

diff --git a/include/secp256k1_generator.h b/include/secp256k1_generator.h
@@ -29,7 +29,7 @@ SECP256K1_API const secp256k1_generator *secp256k1_generator_h;
 /** Parse a 33-byte generator byte sequence into a generator object.
  *
  *  Returns: 1 if input contains a valid generator.
- *  Args: ctx:      a secp256k1 context object.
+ *  Args: ctx:      pointer to a context object
  *  Out:  gen:      pointer to the output generator object
  *  In:   input:    pointer to a 33-byte serialized generator
  */
@@ -42,9 +42,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_generator_parse(
 /** Serialize a 33-byte generator into a serialized byte sequence.
  *
  *  Returns: 1 always.
- *  Args:   ctx:        a secp256k1 context object.
- *  Out:    output:     a pointer to a 33-byte byte array
- *  In:     gen:        a pointer to a generator
+ *  Args:   ctx:        pointer to a context object
+ *  Out:    output:     pointer to a 33-byte byte array
+ *  In:     gen:        pointer to a generator object
  */
 SECP256K1_API int secp256k1_generator_serialize(
     const secp256k1_context *ctx,
@@ -56,8 +56,8 @@ SECP256K1_API int secp256k1_generator_serialize(
  *
  *  Returns: 0 in the highly unlikely case the seed is not acceptable,
  *           1 otherwise.
- *  Args: ctx:     a secp256k1 context object
- *  Out:  gen:     a generator object
+ *  Args: ctx:     pointer to a context object
+ *  Out:  gen:     pointer to a the new generator object
  *  In:   seed32:  a 32-byte seed
  *
  *  If successful a valid generator will be placed in gen. The produced
@@ -75,8 +75,8 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_generator_generate(
  *
  *  Returns: 0 in the highly unlikely case the seed is not acceptable or when
  *           blind is out of range. 1 otherwise.
- *  Args: ctx:     a secp256k1 context object (not secp256k1_context_static)
- *  Out:  gen:     a generator object
+ *  Args: ctx:     pointer to a context object (not secp256k1_context_static)
+ *  Out:  gen:     pointer to a generator object
  *  In:   seed32:  a 32-byte seed
  *        blind32: a 32-byte secret value to blind the generator with.
  *
@@ -107,7 +107,7 @@ typedef struct {
 /** Parse a 33-byte commitment into a commitment object.
  *
  *  Returns: 1 if input contains a valid commitment.
- *  Args: ctx:      a secp256k1 context object.
+ *  Args: ctx:      pointer to a context object
  *  Out:  commit:   pointer to the output commitment object
  *  In:   input:    pointer to a 33-byte serialized commitment key
  */
@@ -120,9 +120,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_pedersen_commitment_par
 /** Serialize a commitment object into a serialized byte sequence.
  *
  *  Returns: 1 always.
- *  Args:   ctx:        a secp256k1 context object.
- *  Out:    output:     a pointer to a 33-byte byte array
- *  In:     commit:     a pointer to a secp256k1_pedersen_commitment containing an
+ *  Args:   ctx:        pointer to a context object
+ *  Out:    output:     pointer to a 33-byte byte array
+ *  In:     commit:     pointer to a secp256k1_pedersen_commitment containing an
  *                      initialized commitment
  */
 SECP256K1_API int secp256k1_pedersen_commitment_serialize(

diff --git a/include/secp256k1_surjectionproof.h b/include/secp256k1_surjectionproof.h
@@ -56,9 +56,9 @@ typedef struct {
 /** Parse a surjection proof
  *
  *  Returns: 1 when the proof could be parsed, 0 otherwise.
- *  Args: ctx:    a secp256k1 context object
- *  Out:  proof:  a pointer to a proof object
- *  In:   input:  a pointer to the array to parse
+ *  Args: ctx:      pointer to a context object
+ *  Out:  proof:    pointer to a proof object
+ *  In:   input:    pointer to the array to parse
  *        inputlen: length of the array pointed to by input
  *
  *  The proof must consist of:
@@ -79,12 +79,11 @@ SECP256K1_API int secp256k1_surjectionproof_parse(
 /** Serialize a surjection proof
  *
  *  Returns: 1 if enough space was available to serialize, 0 otherwise
- *  Args:   ctx:        a secp256k1 context object
- *  Out:    output:     a pointer to an array to store the serialization
- *  In/Out: outputlen:  a pointer to an integer which is initially set to the
- *                      size of output, and is overwritten with the written
- *                      size.
- *  In:     proof:      a pointer to an initialized proof object
+ *  Args:   ctx:        pointer to a context object
+ *  Out:    output:     pointer to an array to store the serialization
+ *  In/Out: outputlen:  pointer to an integer which is initially set to the size
+ *                      of output, and is overwritten with the written size.
+ *  In:     proof:      pointer to an initialized proof object
  *
  *  See secp256k1_surjectionproof_parse for details about the encoding.
  */
@@ -109,7 +108,7 @@ typedef struct {
  *
  * Returns: the number of inputs for the given proof
  * In:   ctx: pointer to a context object
- *     proof: a pointer to a proof object
+ *     proof: pointer to a proof object
  */
 SECP256K1_API size_t secp256k1_surjectionproof_n_total_inputs(
   const secp256k1_context *ctx,
@@ -120,7 +119,7 @@ SECP256K1_API size_t secp256k1_surjectionproof_n_total_inputs(
  *
  * Returns: the number of inputs for the given proof
  * In:   ctx: pointer to a context object
- *     proof: a pointer to a proof object
+ *     proof: pointer to a proof object
  */
 SECP256K1_API size_t secp256k1_surjectionproof_n_used_inputs(
   const secp256k1_context *ctx,
@@ -131,7 +130,7 @@ SECP256K1_API size_t secp256k1_surjectionproof_n_used_inputs(
  *
  * Returns: the total size
  * In:   ctx: pointer to a context object
- *     proof: a pointer to a proof object
+ *     proof: pointer to a proof object
  */
 SECP256K1_API size_t secp256k1_surjectionproof_serialized_size(
   const secp256k1_context *ctx,
@@ -156,7 +155,7 @@ SECP256K1_API size_t secp256k1_surjectionproof_serialized_size(
  *                        limited to 256 the probability of giving up is smaller than
  *                        (255/256)^(n_input_tags_to_use*max_n_iterations).
  *
- *         random_seed32: a random seed to be used for input selection
+ *         random_seed32: random seed to be used for input selection
  * Out:            proof: The proof whose bitvector will be initialized. In case of failure,
  *                        the state of the proof is undefined.
  *          input_index: The index of the actual input that is secretly mapped to the output
@@ -179,8 +178,8 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_surjectionproof_initial
  *         n: inputs were selected after n iterations of random selection
  *
  * In:               ctx: pointer to a context object
- *           proof_out_p: a pointer to a pointer to `secp256k1_surjectionproof*`.
- *                        the newly-allocated struct pointer will be saved here.
+ *           proof_out_p: pointer to a pointer to `secp256k1_surjectionproof*`.
+ *                        The newly-allocated struct pointer will be saved here.
  *      fixed_input_tags: fixed input tags `A_i` for all inputs. (If the fixed tag is not known,
  *                        e.g. in a coinjoin with others' inputs, an ephemeral tag can be given;
  *                        this won't match the output tag but might be used in the anonymity set.)
@@ -192,8 +191,8 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_surjectionproof_initial
  *                        limited to 256 the probability of giving up is smaller than
  *                        (255/256)^(n_input_tags_to_use*max_n_iterations).
  *
- *         random_seed32: a random seed to be used for input selection
- * Out:      proof_out_p: The pointer to newly-allocated proof whose bitvector will be initialized.
+ *         random_seed32: random seed to be used for input selection
+ * Out:      proof_out_p: pointer to newly-allocated proof whose bitvector will be initialized.
  *                        In case of failure, the pointer will be NULL.
  *          input_index: The index of the actual input that is secretly mapped to the output
  */

diff --git a/include/secp256k1_whitelist.h b/include/secp256k1_whitelist.h
@@ -40,9 +40,9 @@ typedef struct {
 /** Parse a whitelist signature
  *
  *  Returns: 1 when the signature could be parsed, 0 otherwise.
- *  Args: ctx:    a secp256k1 context object
- *  Out:  sig:    a pointer to a signature object
- *  In:   input:  a pointer to the array to parse
+ *  Args: ctx:    pointer to a context object
+ *  Out:  sig:    pointer to a signature object
+ *  In:   input:  pointer to the array to parse
  *    input_len:  the length of the above array
  *
  *  The signature must consist of a 1-byte n_keys value, followed by a 32-byte
@@ -67,7 +67,7 @@ SECP256K1_API int secp256k1_whitelist_signature_parse(
 /** Returns the number of keys a signature expects to have.
  *
  *  Returns: the number of keys for the given signature
- *  In: sig: a pointer to a signature object
+ *  In: sig: pointer to a signature object
  */
 SECP256K1_API size_t secp256k1_whitelist_signature_n_keys(
     const secp256k1_whitelist_signature *sig
@@ -76,10 +76,10 @@ SECP256K1_API size_t secp256k1_whitelist_signature_n_keys(
 /** Serialize a whitelist signature
  *
  *  Returns: 1
- *  Args:   ctx:        a secp256k1 context object
- *  Out:    output64:   a pointer to an array to store the serialization
+ *  Args:   ctx:        pointer to a context object
+ *  Out:    output64:   pointer to an array to store the serialization
  *  In/Out: output_len: length of the above array, updated with the actual serialized length
- *  In:     sig:        a pointer to an initialized signature object
+ *  In:     sig:        pointer to an initialized signature object
  *
  *  See secp256k1_whitelist_signature_parse for details about the encoding.
  */