Update getTimezoneOffset JSDoc for clarity

[raynauds]

⚙ Compilation target

es5

⚙ Library

5.1.6

Missing / Incorrect Definition

getTimezoneOffset

In "/src/lib/es5.d.ts", in the Date interface, the JSDoc of getTimezoneOffset implies that the operation is "local time minus UTC time", but the actual operation performed is "UTC time minus local time".

Current JSDoc of getTimezoneOffset:

• Gets the difference in minutes between the time on the local computer and Universal Coordinated Time (UTC).

Suggestion based on the wording on the MDN and W3C documentations for getTimezoneOffset:

• Gets the difference in minutes between Universal Coordinated Time (UTC) and the time on the local computer.

Sample Code

/**
 * returns -60 when run on a machine in timezone UTC+1,
 * which is the expected output according to the MDN and W3C descriptions,
 * but the JSDoc in "/src/lib/es5.d.ts" implies that the result should be 60.
 * local time is 10:00, UTC is 09:00, so according to getTimezoneOffset JSDoc
 * "Gets the difference in minutes between the time on the local computer and Universal Coordinated Time (UTC).":
 * result = local time - UTC = 10:00 - 9:00 = 1:00 -> 60 (minutes)
 */
const result = new Date('2024-01-01T09:00:00.000Z').getTimezoneOffset()

Documentation Link

MDN getTimezoneOffset

The getTimezoneOffset() method of Date instances returns the difference, in minutes, between this date as evaluated in the UTC time zone, and the same date as evaluated in the local time zone.

W3C getTimezoneOffset

Get the difference between UTC time and local time

[raynauds]

Pull request for this issue: #58004