Merge #1476: include: make docs more consistent

da7bc1b include: in doc, remove article in front of "pointer" (Jonas Nick)
aa3dd52 include: make doc about ctx more consistent (Jonas Nick)
e3f6900 include: remove obvious "cannot be NULL" doc (Jonas Nick)

Pull request description:

ACKs for top commit:
  sipa:
    ACK da7bc1b
  real-or-random:
    ACK da7bc1b

Tree-SHA512: 809f312fa0cd1e9502ac79b8a1c502b87e6dfc2db8ad6bbd96d7ddbdaadad0c3b6110fa704b770c353cd34d5bf5547541cbb5f2779425d7419b584e721c854c2

Author: jonasnick

contrib/lax_der_parsing.h

@@ -67,8 +67,8 @@ extern "C" {
  *
  *  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 signature to be parsed
+ *  Out:  sig:      pointer to a signature object
+ *  In:   input:    pointer to the signature to be parsed
  *        inputlen: the length of the array pointed to be input
  *
  *  This function will accept any valid DER encoded signature, even if the

include/secp256k1.h

@@ -265,7 +265,7 @@ SECP256K1_API void secp256k1_selftest(void);
  *  memory allocation entirely, see secp256k1_context_static and the functions in
  *  secp256k1_preallocated.h.
  *
- *  Returns: a newly created context object.
+ *  Returns: pointer to a newly created context object.
  *  In:      flags: Always set to SECP256K1_CONTEXT_NONE (see below).
  *
  *  The only valid non-deprecated flag in recent library versions is
@@ -296,8 +296,8 @@ SECP256K1_API secp256k1_context *secp256k1_context_create(
  *  Cloning secp256k1_context_static is not possible, and should not be emulated by
  *  the caller (e.g., using memcpy). Create a new context instead.
  *
- *  Returns: a newly created context object.
- *  Args:    ctx: an existing context to copy (not secp256k1_context_static)
+ *  Returns: pointer to a newly created context object.
+ *  Args:    ctx: pointer to a context to copy (not secp256k1_context_static).
  */
 SECP256K1_API secp256k1_context *secp256k1_context_clone(
     const secp256k1_context *ctx
@@ -313,7 +313,7 @@ SECP256K1_API secp256k1_context *secp256k1_context_clone(
  *  behaviour is undefined. In that case, secp256k1_context_preallocated_destroy must
  *  be used instead.
  *
- *  Args:   ctx: an existing context to destroy, constructed using
+ *  Args:   ctx: pointer to a context to destroy, constructed using
  *               secp256k1_context_create or secp256k1_context_clone
  *               (i.e., not secp256k1_context_static).
  */
@@ -350,8 +350,8 @@ SECP256K1_API void secp256k1_context_destroy(
  *  fails. In this case, the corresponding default handler will be called with
  *  the data pointer argument set to NULL.
  *
- *  Args: ctx:  an existing context object.
- *  In:   fun:  a pointer to a function to call when an illegal argument is
+ *  Args: ctx:  pointer to a context object.
+ *  In:   fun:  pointer to a function to call when an illegal argument is
  *              passed to the API, taking a message and an opaque pointer.
  *              (NULL restores the default handler.)
  *        data: the opaque pointer to pass to fun above, must be NULL for the default handler.
@@ -377,8 +377,8 @@ SECP256K1_API void secp256k1_context_set_illegal_callback(
  *  for that). After this callback returns, anything may happen, including
  *  crashing.
  *
- *  Args: ctx:  an existing context object.
- *  In:   fun:  a pointer to a function to call when an internal error occurs,
+ *  Args: ctx:  pointer to a context object.
+ *  In:   fun:  pointer to a function to call when an internal error occurs,
  *              taking a message and an opaque pointer (NULL restores the
  *              default handler, see secp256k1_context_set_illegal_callback
  *              for details).
@@ -395,7 +395,7 @@ SECP256K1_API void secp256k1_context_set_error_callback(
 /** Create a secp256k1 scratch space object.
  *
  *  Returns: a newly created scratch space.
- *  Args: ctx:  an existing context object.
+ *  Args: ctx:  pointer to a context object.
  *  In:   size: amount of memory to be available as scratch space. Some extra
  *              (<100 bytes) will be allocated for extra accounting.
  */
@@ -407,7 +407,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT secp256k1_scratch_space *secp256k1_sc
 /** Destroy a secp256k1 scratch space.
  *
  *  The pointer may not be used afterwards.
- *  Args:       ctx: a secp256k1 context object.
+ *  Args:       ctx: pointer to a context object.
  *          scratch: space to destroy
  */
 SECP256K1_API void secp256k1_scratch_space_destroy(
@@ -419,7 +419,7 @@ SECP256K1_API void secp256k1_scratch_space_destroy(
  *
  *  Returns: 1 if the public key was fully valid.
  *           0 if the public key could not be parsed or is invalid.
- *  Args: ctx:      a secp256k1 context object.
+ *  Args: ctx:      pointer to a context object.
  *  Out:  pubkey:   pointer to a pubkey object. If 1 is returned, it is set to a
  *                  parsed version of input. If not, its value is undefined.
  *  In:   input:    pointer to a serialized public key
@@ -439,14 +439,14 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_parse(
 /** Serialize a pubkey object into a serialized byte sequence.
  *
  *  Returns: 1 always.
- *  Args:   ctx:        a secp256k1 context object.
- *  Out:    output:     a pointer to a 65-byte (if compressed==0) or 33-byte (if
+ *  Args:   ctx:        pointer to a context object.
+ *  Out:    output:     pointer to a 65-byte (if compressed==0) or 33-byte (if
  *                      compressed==1) byte array to place the serialized key
  *                      in.
- *  In/Out: outputlen:  a pointer to an integer which is initially set to the
+ *  In/Out: outputlen:  pointer to an integer which is initially set to the
  *                      size of output, and is overwritten with the written
  *                      size.
- *  In:     pubkey:     a pointer to a secp256k1_pubkey containing an
+ *  In:     pubkey:     pointer to a secp256k1_pubkey containing an
  *                      initialized public key.
  *          flags:      SECP256K1_EC_COMPRESSED if serialization should be in
  *                      compressed format, otherwise SECP256K1_EC_UNCOMPRESSED.
@@ -464,7 +464,7 @@ SECP256K1_API int secp256k1_ec_pubkey_serialize(
  *  Returns: <0 if the first public key is less than the second
  *           >0 if the first public key is greater than the second
  *           0 if the two public keys are equal
- *  Args: ctx:      a secp256k1 context object.
+ *  Args: ctx:      pointer to a context object
  *  In:   pubkey1:  first public key to compare
  *        pubkey2:  second public key to compare
  */
@@ -477,9 +477,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_cmp(
 /** Parse an ECDSA signature in compact (64 bytes) format.
  *
  *  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:   input64:  a pointer to the 64-byte array to parse
+ *  Args: ctx:      pointer to a context object
+ *  Out:  sig:      pointer to a signature object
+ *  In:   input64:  pointer to the 64-byte array to parse
  *
  *  The signature must consist of a 32-byte big endian R value, followed by a
  *  32-byte big endian S value. If R or S fall outside of [0..order-1], the
@@ -498,9 +498,9 @@ SECP256K1_API int secp256k1_ecdsa_signature_parse_compact(
 /** Parse a DER ECDSA 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 signature to be parsed
+ *  Args: ctx:      pointer to a context object
+ *  Out:  sig:      pointer to a signature object
+ *  In:   input:    pointer to the signature to be parsed
  *        inputlen: the length of the array pointed to be input
  *
  *  This function will accept any valid DER encoded signature, even if the
@@ -520,13 +520,13 @@ SECP256K1_API int secp256k1_ecdsa_signature_parse_der(
 /** Serialize an ECDSA signature in DER format.
  *
  *  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 DER serialization
- *  In/Out: outputlen: a pointer to a length integer. Initially, this integer
+ *  Args:   ctx:       pointer to a context object
+ *  Out:    output:    pointer to an array to store the DER serialization
+ *  In/Out: outputlen: pointer to a length integer. Initially, this integer
  *                     should be set to the length of output. After the call
  *                     it will be set to the length of the serialization (even
  *                     if 0 was returned).
- *  In:     sig:       a pointer to an initialized signature object
+ *  In:     sig:       pointer to an initialized signature object
  */
 SECP256K1_API int secp256k1_ecdsa_signature_serialize_der(
     const secp256k1_context *ctx,
@@ -538,9 +538,9 @@ SECP256K1_API int secp256k1_ecdsa_signature_serialize_der(
 /** Serialize an ECDSA signature in compact (64 byte) format.
  *
  *  Returns: 1
- *  Args:   ctx:       a secp256k1 context object
- *  Out:    output64:  a pointer to a 64-byte array to store the compact serialization
- *  In:     sig:       a pointer to an initialized signature object
+ *  Args:   ctx:       pointer to a context object
+ *  Out:    output64:  pointer to a 64-byte array to store the compact serialization
+ *  In:     sig:       pointer to an initialized signature object
  *
  *  See secp256k1_ecdsa_signature_parse_compact for details about the encoding.
  */
@@ -554,7 +554,7 @@ SECP256K1_API int secp256k1_ecdsa_signature_serialize_compact(
  *
  *  Returns: 1: correct signature
  *           0: incorrect or unparseable signature
- *  Args:    ctx:       a secp256k1 context object.
+ *  Args:    ctx:       pointer to a context object
  *  In:      sig:       the signature being verified.
  *           msghash32: the 32-byte message hash being verified.
  *                      The verifier must make sure to apply a cryptographic
@@ -585,12 +585,12 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_verify(
 /** Convert a signature to a normalized lower-S form.
  *
  *  Returns: 1 if sigin was not normalized, 0 if it already was.
- *  Args: ctx:    a secp256k1 context object
- *  Out:  sigout: a pointer to a signature to fill with the normalized form,
+ *  Args: ctx:    pointer to a context object
+ *  Out:  sigout: pointer to a signature to fill with the normalized form,
  *                or copy if the input was already normalized. (can be NULL if
  *                you're only interested in whether the input was already
  *                normalized).
- *  In:   sigin:  a pointer to a signature to check/normalize (can be identical to sigout)
+ *  In:   sigin:  pointer to a signature to check/normalize (can be identical to sigout)
  *
  *  With ECDSA a third-party can forge a second distinct signature of the same
  *  message, given a single initial signature, but without knowing the key. This

include/secp256k1_ecdh.h

@@ -39,7 +39,7 @@ SECP256K1_API const secp256k1_ecdh_hash_function secp256k1_ecdh_hash_function_de
  *           0: scalar was invalid (zero or overflow) or hashfp returned 0
  *  Args:    ctx:        pointer to a context object.
  *  Out:     output:     pointer to an array to be filled by hashfp.
- *  In:      pubkey:     a pointer to a secp256k1_pubkey containing an initialized public key.
+ *  In:      pubkey:     pointer to a secp256k1_pubkey containing an initialized public key.
  *           seckey:     a 32-byte scalar with which to multiply the point.
  *           hashfp:     pointer to a hash function. If NULL,
  *                       secp256k1_ecdh_hash_function_sha256 is used

include/secp256k1_ellswift.h

@@ -87,7 +87,7 @@ SECP256K1_API const secp256k1_ellswift_xdh_hash_function secp256k1_ellswift_xdh_
  *  Returns: 1 always.
  *  Args:    ctx:        pointer to a context object
  *  Out:     ell64:      pointer to a 64-byte array to be filled
- *  In:      pubkey:     a pointer to a secp256k1_pubkey containing an
+ *  In:      pubkey:     pointer to a secp256k1_pubkey containing an
  *                       initialized public key
  *           rnd32:      pointer to 32 bytes of randomness
  *
@@ -169,7 +169,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ellswift_create(
  *                      (will not be NULL)
  *           ell_b64:   pointer to the 64-byte encoded public key of party B
  *                      (will not be NULL)
- *           seckey32:  a pointer to our 32-byte secret key
+ *           seckey32:  pointer to our 32-byte secret key
  *           party:     boolean indicating which party we are: zero if we are
  *                      party A, non-zero if we are party B. seckey32 must be
  *                      the private key corresponding to that party's ell_?64.

include/secp256k1_extrakeys.h

@@ -39,7 +39,7 @@ typedef struct {
  *  Returns: 1 if the public key was fully valid.
  *           0 if the public key could not be parsed or is invalid.
  *
- *  Args:   ctx: a secp256k1 context object.
+ *  Args:   ctx: pointer to a context object.
  *  Out: pubkey: pointer to a pubkey object. If 1 is returned, it is set to a
  *               parsed version of input. If not, it's set to an invalid value.
  *  In: input32: pointer to a serialized xonly_pubkey.
@@ -54,9 +54,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_parse(
  *
  *  Returns: 1 always.
  *
- *  Args:     ctx: a secp256k1 context object.
- *  Out: output32: a pointer to a 32-byte array to place the serialized key in.
- *  In:    pubkey: a pointer to a secp256k1_xonly_pubkey containing an initialized public key.
+ *  Args:     ctx: pointer to a context object.
+ *  Out: output32: pointer to a 32-byte array to place the serialized key in.
+ *  In:    pubkey: pointer to a secp256k1_xonly_pubkey containing an initialized public key.
  */
 SECP256K1_API int secp256k1_xonly_pubkey_serialize(
     const secp256k1_context *ctx,
@@ -69,7 +69,7 @@ SECP256K1_API int secp256k1_xonly_pubkey_serialize(
  *  Returns: <0 if the first public key is less than the second
  *           >0 if the first public key is greater than the second
  *           0 if the two public keys are equal
- *  Args: ctx:      a secp256k1 context object.
+ *  Args: ctx:      pointer to a context object.
  *  In:   pubkey1:  first public key to compare
  *        pubkey2:  second public key to compare
  */

include/secp256k1_preallocated.h

@@ -52,8 +52,8 @@ SECP256K1_API size_t secp256k1_context_preallocated_size(
  *  in the memory. In simpler words, the prealloc pointer (or any pointer derived
  *  from it) should not be used during the lifetime of the context object.
  *
- *  Returns: a newly created context object.
- *  In:      prealloc: a pointer to a rewritable contiguous block of memory of
+ *  Returns: pointer to newly created context object.
+ *  In:      prealloc: pointer to a rewritable contiguous block of memory of
  *                     size at least secp256k1_context_preallocated_size(flags)
  *                     bytes, as detailed above.
  *           flags:    which parts of the context to initialize.
@@ -72,7 +72,7 @@ SECP256K1_API secp256k1_context *secp256k1_context_preallocated_create(
  *  caller-provided memory.
  *
  *  Returns: the required size of the caller-provided memory block.
- *  In:      ctx: an existing context to copy.
+ *  In:      ctx: pointer to a context to copy.
  */
 SECP256K1_API size_t secp256k1_context_preallocated_clone_size(
     const secp256k1_context *ctx
@@ -91,9 +91,9 @@ SECP256K1_API size_t secp256k1_context_preallocated_clone_size(
  *  Cloning secp256k1_context_static is not possible, and should not be emulated by
  *  the caller (e.g., using memcpy). Create a new context instead.
  *
- *  Returns: a newly created context object.
- *  Args:    ctx:      an existing context to copy (not secp256k1_context_static).
- *  In:      prealloc: a pointer to a rewritable contiguous block of memory of
+ *  Returns: pointer to a newly created context object.
+ *  Args:    ctx:      pointer to a context to copy (not secp256k1_context_static).
+ *  In:      prealloc: pointer to a rewritable contiguous block of memory of
  *                     size at least secp256k1_context_preallocated_size(flags)
  *                     bytes, as detailed above.
  */
@@ -118,7 +118,7 @@ SECP256K1_API secp256k1_context *secp256k1_context_preallocated_clone(
  *  preallocated pointer given to secp256k1_context_preallocated_create or
  *  secp256k1_context_preallocated_clone.
  *
- *  Args:   ctx: an existing context to destroy, constructed using
+ *  Args:   ctx: pointer to a context to destroy, constructed using
  *               secp256k1_context_preallocated_create or
  *               secp256k1_context_preallocated_clone
  *               (i.e., not secp256k1_context_static).

include/secp256k1_recovery.h

@@ -28,9 +28,9 @@ typedef struct {
 /** Parse a compact ECDSA signature (64 bytes + recovery id).
  *
  *  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:   input64: a pointer to a 64-byte compact signature
+ *  Args: ctx:     pointer to a context object
+ *  Out:  sig:     pointer to a signature object
+ *  In:   input64: pointer to a 64-byte compact signature
  *        recid:   the recovery id (0, 1, 2 or 3)
  */
 SECP256K1_API int secp256k1_ecdsa_recoverable_signature_parse_compact(
@@ -43,9 +43,9 @@ SECP256K1_API int secp256k1_ecdsa_recoverable_signature_parse_compact(
 /** Convert a recoverable signature into a normal signature.
  *
  *  Returns: 1
- *  Args: ctx:    a secp256k1 context object.
- *  Out:  sig:    a pointer to a normal signature.
- *  In:   sigin:  a pointer to a recoverable signature.
+ *  Args: ctx:    pointer to a context object.
+ *  Out:  sig:    pointer to a normal signature.
+ *  In:   sigin:  pointer to a recoverable signature.
  */
 SECP256K1_API int secp256k1_ecdsa_recoverable_signature_convert(
     const secp256k1_context *ctx,
@@ -56,10 +56,10 @@ SECP256K1_API int secp256k1_ecdsa_recoverable_signature_convert(
 /** Serialize an ECDSA signature in compact format (64 bytes + recovery id).
  *
  *  Returns: 1
- *  Args: ctx:      a secp256k1 context object.
- *  Out:  output64: a pointer to a 64-byte array of the compact signature.
- *        recid:    a pointer to an integer to hold the recovery id.
- *  In:   sig:      a pointer to an initialized signature object.
+ *  Args: ctx:      pointer to a context object.
+ *  Out:  output64: pointer to a 64-byte array of the compact signature.
+ *        recid:    pointer to an integer to hold the recovery id.
+ *  In:   sig:      pointer to an initialized signature object.
  */
 SECP256K1_API int secp256k1_ecdsa_recoverable_signature_serialize_compact(
     const secp256k1_context *ctx,

include/secp256k1_schnorrsig.h

@@ -169,11 +169,11 @@ SECP256K1_API int secp256k1_schnorrsig_sign_custom(
  *
  *  Returns: 1: correct signature
  *           0: incorrect signature
- *  Args:    ctx: a secp256k1 context object.
+ *  Args:    ctx: pointer to a context object.
  *  In:    sig64: pointer to the 64-byte signature to verify.
  *           msg: the message being verified. Can only be NULL if msglen is 0.
  *        msglen: length of the message
- *        pubkey: pointer to an x-only public key to verify with (cannot be NULL)
+ *        pubkey: pointer to an x-only public key to verify with
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_schnorrsig_verify(
     const secp256k1_context *ctx,