1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Tidy up QTimeZone documentation

Browse Source 
Update to reflect changes in reality now that I can more faithfully
describe what's happening (thanks to lessons learned during L10n of
display names, though that work isn't in 6.8).

Pick-to: 6.5
Change-Id: I248c924af598c8e8d6cd84675ac04e1733927355
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 1dd785d10d69b0705f86e1580c058d8cd017798b)
This commit is contained in:
Edward Welbourne 2024-08-28 11:33:57 +02:00
parent 1212298fb4
commit 450dd785c0
1 changed files with 34 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
src/corelib/time/qtimezone.cpp
View File

@ -322,10 +322,10 @@ Q_GLOBAL_STATIC(QTimeZoneSingleton, global_tz);
The time zone offset data for a given moment in time.
This provides the time zone offsets and abbreviation to use at that moment
in time. When a function returns this type, it may use an invalid datetime
to indicate that the query it is answering has no valid answer, so check
\c{atUtc.isValid()} before using the results.
This provides the time zone offsets and abbreviation to use at a given
moment in time. When a function returns this type, it may use an invalid
datetime to indicate that the query it is answering has no valid answer, so
check \c{atUtc.isValid()} before using the results.
\list
\li OffsetData::atUtc The datetime of the offset data in UTC time.
@ -514,9 +514,10 @@ QTimeZone::QTimeZone(int offsetSeconds)
by territory(). The \a comment is an optional note that may be displayed in
a GUI to assist users in selecting a time zone.
The \a zoneId \e{must not} be one of the available system IDs returned by
availableTimeZoneIds(). The \a offsetSeconds from UTC must be in the range
-16 hours to +16 hours.
The \a offsetSeconds from UTC must be in the range -16 hours to +16 hours.
The \a zoneId \e{must not} be an ID for which isTimeZoneIdAvailable() is
true, unless it is a UTC-offset name that doesn't appear in
availableTimeZoneIds().
If the custom time zone does not have a specific territory then set it to the
default value of QLocale::AnyTerritory.
@ -922,15 +923,15 @@ QString QTimeZone::comment() const
}
/*!
Returns the localized time zone display name at the given \a atDateTime
for the given \a nameType in the given \a locale. The \a nameType and
\a locale requested may not be supported on all platforms, in which case
the best available option will be returned.
Returns the localized time zone display name.
If the \a locale is not provided then the application default locale will
be used.
The name returned is the one for the given \a locale, applicable at the
given \a atDateTime, and of the form indicated by \a nameType. The display
name may change depending on DST or historical events.
The display name may change depending on DST or historical events.
If the \a locale is not provided, then the application default locale will
be used. For custom timezones created by client code, the data supplied to
the constructor are used, as no localization data will be available for it.
This method is only available when feature \c timezone is enabled.
@ -960,16 +961,16 @@ QString QTimeZone::displayName(const QDateTime &atDateTime, NameType nameType,
}
/*!
Returns the localized time zone display name for the given \a timeType
and \a nameType in the given \a locale. The \a nameType and \a locale
requested may not be supported on all platforms, in which case the best
available option will be returned.
Returns the localized time zone display name.
If the \a locale is not provided then the application default locale will
be used.
The name returned is the one for the given \a locale, applicable when the
given \a timeType is in effect and of the form indicated by \a nameType.
Where the time zone display names have changed over time, the current names
will be used.
Where the time zone display names have changed over time then the most
recent names will be used.
If the \a locale is not provided, then the application default locale will
be used. For custom timezones created by client code, the data supplied to
the constructor are used, as no localization data will be available for it.
This method is only available when feature \c timezone is enabled.
@ -998,11 +999,14 @@ QString QTimeZone::displayName(TimeType timeType, NameType nameType,
}
/*!
Returns the time zone abbreviation at the given \a atDateTime. The
abbreviation may change depending on DST or even historical events.
Returns the time zone abbreviation at the given \a atDateTime.
Note that the abbreviation is not guaranteed to be unique to this time zone
and should not be used in place of the ID or display name.
The abbreviation may change depending on DST or even historical events.
\note The abbreviation is not guaranteed to be unique to this time zone and
should not be used in place of the ID or display name. The abbreviation may
be localized, depending on the underlying operating system. To get consistent
localization, use \c {displayName(atDateTime, QTimeZone::ShortName, locale)}.
This method is only available when feature \c timezone is enabled.
@ -1194,9 +1198,10 @@ bool QTimeZone::isDaylightTime(const QDateTime &atDateTime) const
Returns the effective offset details at the given \a forDateTime.
This is the equivalent of calling abbreviation() and all three offset
functions individually but is more efficient. If this data is not available
for the given datetime, an invalid OffsetData will be returned with an
invalid QDateTime as its \c atUtc.
functions individually but may be more efficient and may get a different
localization for the abbreviation. If this data is not available for the
given datetime, an invalid OffsetData will be returned with an invalid
QDateTime as its \c atUtc.
This method is only available when feature \c timezone is enabled.