Merge #1727: docs: Clarify that callback can be called more than once

4d90585 docs: Improve API docs of _context_set_illegal_callback (Tim Ruffing)
895f53d docs: Clarify that callback can be called more than once (Tim Ruffing)

Pull request description:

  The tests in #1698 reminded me that some functions, e.g., `secp256k1_ec_pubkey_cmp`, may call the illegal callback more than once (see #1390 (comment) for more context). This PR clarifies the API docs to state explicitly that this is possible.

  This is the simplest solution. Any production code should crash anyway if it encounters a callback. And in debug code or in our test code, it doesn't really matter whether you see an error message once or twice.

  The alternative is to provide a guarantee that the callback is called only once. But that would make our code more complex for no good reason.

  The second commit fixes a few typos, wording, and consistency.

ACKs for top commit:
  stratospher:
    ACK 4d90585.
  theStack:
    re-ACK 4d90585

Tree-SHA512: 97c31d68851e845b21e9ec2530432603917c019580feba98b62014b538f61be94ba963bf619217720d8f7331ac830e97e62c76c02e7297d3cf73dd085e6f4ca2

Author: real-or-random

include/secp256k1.h

@@ -261,7 +261,7 @@ SECP256K1_DEPRECATED("Use secp256k1_context_static instead");
  *  secp256k1_context_create (or secp256k1_context_preallocated_create), which will
  *  take care of performing the self tests.
  *
- *  If the tests fail, this function will call the default error handler to abort the
+ *  If the tests fail, this function will call the default error callback to abort the
  *  program (see secp256k1_context_set_error_callback).
  */
 SECP256K1_API void secp256k1_selftest(void);
@@ -334,36 +334,37 @@ SECP256K1_API void secp256k1_context_destroy(
  *  an API call. It will only trigger for violations that are mentioned
  *  explicitly in the header.
  *
- *  The philosophy is that these shouldn't be dealt with through a
- *  specific return value, as calling code should not have branches to deal with
- *  the case that this code itself is broken.
+ *  The philosophy is that these shouldn't be dealt with through a specific
+ *  return value, as calling code should not have branches to deal with the case
+ *  that this code itself is broken.
  *
  *  On the other hand, during debug stage, one would want to be informed about
- *  such mistakes, and the default (crashing) may be inadvisable.
- *  When this callback is triggered, the API function called is guaranteed not
- *  to cause a crash, though its return value and output arguments are
- *  undefined.
- *
- *  When this function has not been called (or called with fn==NULL), then the
- *  default handler will be used. The library provides a default handler which
- *  writes the message to stderr and calls abort. This default handler can be
+ *  such mistakes, and the default (crashing) may be inadvisable. Should this
+ *  callback return instead of crashing, the return value and output arguments
+ *  of the API function call are undefined. Moreover, the same API call may
+ *  trigger the callback again in this case.
+ *
+ *  When this function has not been called (or called with fun==NULL), then the
+ *  default callback will be used. The library provides a default callback which
+ *  writes the message to stderr and calls abort. This default callback can be
  *  replaced at link time if the preprocessor macro
  *  USE_EXTERNAL_DEFAULT_CALLBACKS is defined, which is the case if the build
  *  has been configured with --enable-external-default-callbacks. Then the
  *  following two symbols must be provided to link against:
  *   - void secp256k1_default_illegal_callback_fn(const char *message, void *data);
  *   - void secp256k1_default_error_callback_fn(const char *message, void *data);
- *  The library can call these default handlers even before a proper callback data
+ *  The library may call a default callback even before a proper callback data
  *  pointer could have been set using secp256k1_context_set_illegal_callback or
  *  secp256k1_context_set_error_callback, e.g., when the creation of a context
- *  fails. In this case, the corresponding default handler will be called with
+ *  fails. In this case, the corresponding default callback will be called with
  *  the data pointer argument set to NULL.
  *
  *  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.
+ *              (NULL restores the default callback.)
+ *        data: the opaque pointer to pass to fun above, must be NULL for the
+ *              default callback.
  *
  *  See also secp256k1_context_set_error_callback.
  */
@@ -380,18 +381,19 @@ SECP256K1_API void secp256k1_context_set_illegal_callback(
  *  to abort the program.
  *
  *  This can only trigger in case of a hardware failure, miscompilation,
- *  memory corruption, serious bug in the library, or other error would can
- *  otherwise result in undefined behaviour. It will not trigger due to mere
+ *  memory corruption, serious bug in the library, or other error that would
+ *  result in undefined behaviour. It will not trigger due to mere
  *  incorrect usage of the API (see secp256k1_context_set_illegal_callback
  *  for that). After this callback returns, anything may happen, including
  *  crashing.
  *
  *  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
+ *              default callback, see secp256k1_context_set_illegal_callback
  *              for details).
- *        data: the opaque pointer to pass to fun above, must be NULL for the default handler.
+ *        data: the opaque pointer to pass to fun above, must be NULL for the
+ *              default callback.
  *
  *  See also secp256k1_context_set_illegal_callback.
  */