[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 1/2] Add conversions to and from struct timespec to module in
From: |
Eli Zaretskii |
Subject: |
Re: [PATCH 1/2] Add conversions to and from struct timespec to module interface. |
Date: |
Wed, 24 Apr 2019 10:21:52 +0300 |
> From: Philipp Stephani <address@hidden>
> Cc: Philipp Stephani <address@hidden>
> Date: Tue, 23 Apr 2019 23:32:17 +0200
>
> address@hidden Function struct timespec extract_time (emacs_env
> address@hidden, emacs_value @var{time})
> +This function, which is available since Emacs 27, interprets
> address@hidden as an Emacs time value and returns the corresponding
> address@hidden 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
> address@hidden 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
> address@hidden 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
> address@hidden 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.
Re: [PATCH 1/2] Add conversions to and from struct timespec to module interface., Paul Eggert, 2019/04/23
Message not availableRe: [PATCH 2/2] Add module functions to convert from and to big integers., Eli Zaretskii, 2019/04/24
Re: [PATCH 2/2] Add module functions to convert from and to big integers., Philipp Stephani, 2019/04/24
Re: [PATCH 2/2] Add module functions to convert from and to big integers., Eli Zaretskii, 2019/04/24
Re: [PATCH 2/2] Add module functions to convert from and to big integers., Philipp Stephani, 2019/04/24
Re: [PATCH 2/2] Add module functions to convert from and to big integers., Eli Zaretskii, 2019/04/24
Re: [PATCH 2/2] Add module functions to convert from and to big integers., Philipp Stephani, 2019/04/24
Re: [PATCH 2/2] Add module functions to convert from and to big integers., Eli Zaretskii, 2019/04/24
Re: [PATCH 2/2] Add module functions to convert from and to big integers., Philipp Stephani, 2019/04/24