bug#55635: `make-decoded-time' incorrectly sets DST to nil, it should be -1 (guess)

[Paul Eggert <eggert@cs.ucla.edu>]

[-- Attachment #1: Type: text/plain, Size: 986 bytes --]

On 5/31/22 05:25, Maxim Nikulin wrote:

> I have never used `cl-defstruct' before (and frankly speaking I am 
> rather confused that the `decoded-time' struct and its constructor 
> `make-decoded-time' are defined in different files and even directories 
> are not the same), so my question may be naïve. Why did not you just add 
> this new sentence to the :documentation property of the DST slot a bit 
> above?

I am not sure I understand the question. The slot itself has a specified 
value (t, nil, or -1) whereas the decoded-time-dst function returns an 
unspecified value when there is no slot.

> By the way, after updating of `make-decoded-time', default value for DST 
> should be updated in `cl-defstruct' as well, otherwise
>      (describe-symbol 'decoded-time)
> reports that the default is nil.
> 
> It may be reasonable to cross-link `decoded-time' and 
> `make-decoded-time' in docstrings.

Thanks for the suggestions; I installed the attached.

[-- Attachment #2: 0001-Default-decoded-time-dst-slot-to-1.patch --]
[-- Type: text/x-patch, Size: 2667 bytes --]

From 5678829a62752eb332caef3abebeb64cb0722708 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 13 Jun 2022 14:25:58 -0700
Subject: [PATCH] Default decoded-time dst slot to -1

* lisp/simple.el (decoded-time): Default dst slot to -1.
Improve related doc strings.
---
 lisp/calendar/time-date.el |  3 ++-
 lisp/simple.el             | 16 ++++++++++------
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/lisp/calendar/time-date.el b/lisp/calendar/time-date.el
index 40374c3bb4..d19134db83 100644
--- a/lisp/calendar/time-date.el
+++ b/lisp/calendar/time-date.el
@@ -557,7 +557,8 @@ make-decoded-time
   (list second minute hour day month year nil dst zone))
 
 (defun decoded-time-set-defaults (time &optional default-zone)
-  "Set any nil values in `decoded-time' TIME to default values.
+  "Set most nil values in `decoded-time' TIME to default values.
+This can set TIME's year, month, day, hour, minute and second.
 The default value is based on January 1st, 1970 at midnight.
 This year is used to guarantee portability; see Info
 node `(elisp) Time of Day'.
diff --git a/lisp/simple.el b/lisp/simple.el
index f6932339c9..05a0855a96 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -10511,10 +10511,10 @@ capitalize-dwim
   (year nil :documentation "This is a four digit integer.")
   (weekday nil :documentation "\
 This is a number between 0 and 6, and 0 is Sunday.")
-  (dst nil :documentation "\
+  (dst -1 :documentation "\
 This is t if daylight saving time is in effect, nil if it is not
-in effect, and -1 if daylight saving information is not
-available.")
+in effect, and -1 if daylight saving information is not available.
+Also see `decoded-time-dst'.")
   (zone nil :documentation "\
 This is an integer indicating the UTC offset in seconds, i.e.,
 the number of seconds east of Greenwich.")
@@ -10524,9 +10524,13 @@ capitalize-dwim
 ;; It should return -1 indicating unknown DST, but currently returns
 ;; nil indicating standard time.
 (put 'decoded-time-dst 'function-documentation
-     (append (get 'decoded-time-dst 'function-documentation)
-             "As a special case, `decoded-time-dst' returns an unspecified
-value when given a list too short to have a dst element."))
+     "Access slot \"dst\" of `decoded-time' struct CL-X.
+This is t if daylight saving time is in effect, nil if it is not
+in effect, and -1 if daylight saving information is not available.
+As a special case, return an unspecified value when given a list
+too short to have a dst element.
+
+(fn CL-X)")
 
 (defun get-scratch-buffer-create ()
   "Return the *scratch* buffer, creating a new one if needed."
-- 
2.34.1