From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: [PATCH 1/2] Add conversions to and from struct timespec to module interface. Date: Wed, 24 Apr 2019 10:21:52 +0300 Message-ID: <83o94v3m27.fsf@gnu.org> References: <329aec43-8272-f39a-e7ef-e77804103a50@cs.ucla.edu> <20190423213218.35618-1-phst@google.com> Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="45365"; mail-complaints-to="usenet@blaine.gmane.org" Cc: phst@google.com, eggert@cs.ucla.edu, emacs-devel@gnu.org To: Philipp Stephani Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Apr 24 09:36:23 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hJCS7-000Bf1-4C for ged-emacs-devel@m.gmane.org; Wed, 24 Apr 2019 09:36:23 +0200 Original-Received: from localhost ([127.0.0.1]:37311 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hJCS6-0008IP-2h for ged-emacs-devel@m.gmane.org; Wed, 24 Apr 2019 03:36:22 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:47780) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hJCO1-0005hs-NO for emacs-devel@gnu.org; Wed, 24 Apr 2019 03:32:10 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:51960) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hJCEA-0001OA-26; Wed, 24 Apr 2019 03:21:58 -0400 Original-Received: from [176.228.60.248] (port=3798 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1hJCE9-0003rv-GN; Wed, 24 Apr 2019 03:21:57 -0400 In-reply-to: <20190423213218.35618-1-phst@google.com> (message from Philipp Stephani on Tue, 23 Apr 2019 23:32:17 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:235849 Archived-At: > From: Philipp Stephani > Cc: Philipp Stephani > 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.