include: make docs more consistent

Like upstream bitcoin-core/secp256k1#1476 .

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

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)

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(

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
  */

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.
  */