From dc2d89e233fe9d2fd7b31653cc052538ca785688 Mon Sep 17 00:00:00 2001
From: oleibman <10341515+oleibman@users.noreply.github.com>
Date: Sun, 2 Nov 2025 19:58:25 -0800
Subject: [PATCH] Documentation for Excel Date/timestamp Format

Fix #1764.
---
 docs/topics/autofilters.md        |  1 +
 docs/topics/calculation-engine.md | 25 +++++++++++++------------
 2 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/docs/topics/autofilters.md b/docs/topics/autofilters.md
index a80283697..220a6fe37 100644
--- a/docs/topics/autofilters.md
+++ b/docs/topics/autofilters.md
@@ -176,6 +176,7 @@ $columnFilter->createRule()
 In MS Excel, DateGroup filters provide a series of dropdown filter
 selectors for date values, so you can specify entire years, or months
 within a year, or individual days within each month.
+Note that cells covered by such a filter are expected to be in [Excel DateTime Format](./calculation-engine.md#excel-timestamps).
 
 ![04-02-dategroup-autofilter.png](./images/04-02-dategroup-autofilter.png)
 
diff --git a/docs/topics/calculation-engine.md b/docs/topics/calculation-engine.md
index ca628c0a7..c6450235c 100644
--- a/docs/topics/calculation-engine.md
+++ b/docs/topics/calculation-engine.md
@@ -194,20 +194,22 @@ Time functions in Excel will be a PHP `DateTime` object.
 
 #### Excel Timestamps
 
-If `RETURNDATE_EXCEL` is set for the Return Date Type, then the returned
-date value by any access to the Date and Time functions in Excel will be
-a floating point value that represents a number of days from the Excel
-base date. The Excel base date is determined by which calendar Excel
+Excel timestamps are stored as integer or floating point, where the integer portion represents the number of days since a base date,
+and the fraction portion represents the time of day (0 is midnight, 0.5 is noon, 0.999... is just before midnight the next day).
+The Excel base date is determined by which calendar Excel
 uses: the Windows 1900 or the Mac 1904 calendar. 1st January 1900 is the
 base date for the Windows 1900 calendar while 1st January 1904 is the
 base date for the Mac 1904 calendar.
 
-It is possible for scripts to change the calendar used for calculating
-Excel date values by calling the
-`\PhpOffice\PhpSpreadsheet\Shared\Date::setExcelCalendar()` method:
+If `RETURNDATE_EXCEL` is set for the Return Date Type, then the returned
+date value by any access to the Date and Time functions in Excel will be
+a floating point value in Excel timestamp format (previous paragraph).
 
+It is possible for scripts to change the calendar used for calculating
+Excel date values by calling:
 ```php
-\PhpOffice\PhpSpreadsheet\Shared\Date::setExcelCalendar($baseDate);
+\PhpOffice\PhpSpreadsheet\Shared\Date::setExcelCalendar($baseDate); // static property, less preferred
+$spreadsheet->setExcelCalendar($baseDate); // instance property, preferred
 ```
 
 where the following constants can be used for `$baseDate`:
@@ -218,11 +220,10 @@ where the following constants can be used for `$baseDate`:
 The method will return a Boolean True on success, False on failure (e.g.
 if an invalid value is passed in).
 
-The `\PhpOffice\PhpSpreadsheet\Shared\Date::getExcelCalendar()` method can
-be used to determine the current value of this setting:
-
+The current value of this setting can be determined via:
 ```php
-$baseDate = \PhpOffice\PhpSpreadsheet\Shared\Date::getExcelCalendar();
+$baseDate = \PhpOffice\PhpSpreadsheet\Shared\Date::getExcelCalendar(); // static
+$baseDate = $spreadsheet->getExcelCalendar(); // instance
 ```
 
 The default is `CALENDAR_WINDOWS_1900`.