Re: [PATCH 2/2] Add module functions to convert from and to big integers.

[Eli Zaretskii <eliz@gnu.org>]

> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Tue, 23 Apr 2019 15:17:42 +0200
> Cc: Philipp Stephani <phst@google.com>
> 
> +@deftypefn Function bool extract_big_integer (emacs_env *@var{env}, emacs_value @var{arg}, int *@var{sign}, ptrdiff_t *@var{size}, unsigned char *@var{magnitude})
> +This function, which is available since Emacs 27, extracts the
> +integral value of @var{arg}.  If @var{sign} is not @code{NULL}, it
> +stores the sign of @var{arg} (-1, 0, or +1) into @code{*sign}.  The
> +magnitude is stored into @var{magnitude} as follows.  If @var{size}
> +and @var{magnitude} are bot non-@code{NULL}, then @var{magnitude} must
> +point to an array of at least @code{*size} bytes.  If @var{magnitude}
> +is large enough to hold the magnitude of @var{arg}, then this function
> +writes the magnitude into the @var{magnitude} array in little-endian
> +form, stores the number of bytes written into @code{*size}, and
> +returns @code{true}.  If @var{magnitude} is not large enough, it
> +stores the required size into @code{*size}, signals an error, and
> +returns @code{false}.  If @var{size} is not @code{NULL} and
> +@var{magnitude} is @code{NULL}, then the function stores the required
> +size into @code{*size} and returns @code{true}.
> +@end deftypefn

I think this text should tell more about how magnitude is put into the
MAGNITUDE array.  I needed to look at the implementation to find the
answer to that question.  Since the caller will have to make sure the
array is "large enough", I think the reader needs to know more about
this than this text reveals.

> +@deftypefn Function emacs_value make_big_integer (emacs_env *@var{env}, int sign, ptrdiff_t size, unsigned char *magnitude)
> +This function, which is available since Emacs 27, takes an
> +arbitrary-sized integer argument and returns a corresponding
> +@code{emacs_value} object.

Same here.  In particular, the text mentions "integer argument", but
it's unclear to what exactly that alludes, as there's no "argument" in
the function's signature as shown.

Thanks.