From c29f28e638599a48741a1c59599cff282f88d633 Mon Sep 17 00:00:00 2001 From: Tim Ruffing Date: Thu, 18 Jan 2024 11:37:18 +0100 Subject: [PATCH] include: make docs more consistent Like upstream https://github.com/bitcoin-core/secp256k1/pull/1476 . --- include/secp256k1_ecdsa_adaptor.h | 8 +++---- include/secp256k1_ecdsa_s2c.h | 20 ++++++++--------- include/secp256k1_generator.h | 24 ++++++++++----------- include/secp256k1_surjectionproof.h | 33 ++++++++++++++--------------- include/secp256k1_whitelist.h | 14 ++++++------ 5 files changed, 49 insertions(+), 50 deletions(-) diff --git a/include/secp256k1_ecdsa_adaptor.h b/include/secp256k1_ecdsa_adaptor.h index 225caa73..e50f94e9 100644 --- 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 index 02b50513..ea4219fe 100644 --- 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 index eacefad8..a0f9fb85 100644 --- 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 index 6fee1e60..c9a4aaee 100644 --- 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 index 096a0ee4..9f9decce 100644 --- 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. */