Re: [PATCH 1/2] Add conversions to and from struct timespec to module interface.

[Eli Zaretskii <eliz@gnu.org>]

> From: Philipp Stephani <p.stephani2@gmail.com>
> Cc: Philipp Stephani <phst@google.com>
> Date: Tue, 23 Apr 2019 23:32:17 +0200
> 
> +@deftypefn Function struct timespec extract_time (emacs_env *@var{env}, emacs_value @var{time})
> +This function, which is available since Emacs 27, interprets
> +@var{time} as an Emacs time value and returns the corresponding
> +@code{struct timespec}.  @xref{Time of Day}.

I think we need to tell something about 'struct timespec' here.
Ideally, simply describe its members, unless they are too platform
dependent.  This text is for C programmers, who will need to look up
the struct to be able to use this function.

>                                            This function signals an
> +error if @var{time} is out of range for @code{struct timespec}.

Instead of "out of range for", I'd prefer saying "cannot be
represented by", perhaps with an example.  "Out of range" is a
complicated subject when talking about time values, and we shouldn't
assume the reader is an expert on time handling.

>                                                                    If
> +@var{time} has higher precision than nanoseconds, then this function
> +truncates it to nanosecond precision.

If we describe 'struct timespec', this sentence will be redundant, I
think.  (Btw, "truncates" or "rounds", and if the former, why not the
latter?)

> +This function, which is available since Emacs 27, takes a @code{struct
> +timespec} argument @var{time} and returns the corresponding Emacs
> +timestamp.  @xref{Time of Day} for the possible return value formats.
                                 ^
There should be a comma there, or makeinfo will produce a warning.

> +It is not specified in which timestamp format the time is returned,
> +but it is always a valid Emacs timestamp.

I question the wisdom of such an obscurity.  There are no secrets
here, as the source code is available, and I can envision use cases
where the programmer does really need to know the structure of the
returned timestamp.  Why should we make this "unspecified"?

>                                           The return value is exactly
> +the same timestamp as @var{time}: all input values are representable,
> +and there is never a loss of precision.  @code{time.tv_sec} and
> +@code{time.tv_nsec} can be arbitrary values.

Here you reference members of 'struct timespec' without describing the
struct first, which I think is confusing.  One more reason to describe
the struct explcitly

> +@code{time.tv_nsec} doesn't have to be in the range [0, 999999999].
                                                       ^^^^^^^^^^^^^^
This should be in @code, and I think using @dots{} instead of the
comma will look better in print.

> +** New module environment functions 'make_time' and 'extract_time' to
> +convert between timespec structures and Emacs time values.
                                           ^^^^^^^^^^^^^^^^^
"Emacs Lisp time values", I'd say.

Thanks.