Skip to content

Fix the API documentation #520

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DimuthuMadushan merged 3 commits into from
Apr 21, 2025
Merged

Fix the API documentation #520

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
436bbfc
Fix the API documentation
daneshk Mar 31, 2025
7ec6d12
Fix the API documentation
daneshk Apr 1, 2025
b6e36f7
Merge branch 'master' into master
DimuthuMadushan Apr 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 15 additions & 15 deletions ballerina/time_apis.bal
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ public isolated function utcAddSeconds(Utc utc, Seconds seconds) returns Utc {
return [secondsFromEpoch, lastSecondFraction];
}

# Returns difference in seconds between `utc1` and `utc2`.
# Returns difference in seconds between two UTC times.
# This will be positive if `utc1` occurs after `utc2`
# ```ballerina
# time:Utc utc1 = time:utcNow();
Expand All @@ -85,7 +85,7 @@ public isolated function utcAddSeconds(Utc utc, Seconds seconds) returns Utc {
# ```
# + utc1 - 1st Utc time as a tuple `[int, decimal]`
# + utc2 - 2nd Utc time as a tuple `[int, decimal]`
# + return - The difference between `utc1` and `utc2` as `Seconds`
# + return - The difference between `utc1` and `utc2` in seconds
public isolated function utcDiffSeconds(Utc utc1, Utc utc2) returns Seconds {
return externUtcDiffSeconds(utc1, utc2);
}
Expand All @@ -106,8 +106,8 @@ public isolated function dateValidate(Date date) returns Error? {
# time:Date date = {year: 1994, month: 11, day: 7};
# time:DayOfWeek day = time:dayOfWeek(date);
# ```
# + date - Date value
# + return - `time:DayOfWeek` if the `date` is valid or else panic
# + date - The date for which the day of the week is to be calculated
# + return - The `time:DayOfWeek` if the `date` is valid or else panic
public isolated function dayOfWeek(Date date) returns DayOfWeek {
DayOfWeek[] daysOfWeek = [SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY];
return daysOfWeek[checkpanic externDayOfWeek(date)];
Expand All @@ -118,18 +118,18 @@ public isolated function dayOfWeek(Date date) returns DayOfWeek {
# time:Utc utc = time:utcNow();
# time:Civil civil = time:utcToCivil(utc);
# ```
# + utc - `time:Utc` timestamp
# + utc - The `time:Utc` timestamp value to be converted
# + return - The corresponding `time:Civil` value
public isolated function utcToCivil(Utc utc) returns Civil {
return externUtcToCivil(utc);
}

# Converts a given `Civil` value to an `Utc` timestamp.
# Converts a given `time:Civil` value to an `time:Utc` timestamp.
# ```ballerina
# time:Civil civil = time:utcToCivil(time:utcNow());
# time:Utc utc = time:utcFromCivil(civil);
# ```
# + civilTime - `time:Civil` time
# + civilTime - The `time:Civil` value to be converted
# + return - The corresponding `time:Utc` value or an error if `civilTime.utcOffset` is missing
public isolated function utcFromCivil(Civil civilTime) returns Utc|Error {
ZoneOffset utcOffset;
Expand All @@ -156,7 +156,7 @@ public isolated function utcFromCivil(Civil civilTime) returns Utc|Error {
# time:Civil|time:Error civil1 = time:civilFromString("2021-04-12T23:20:50.520+05:30[Asia/Colombo]");
# time:Civil|time:Error civil2 = time:civilFromString("2007-12-03T10:15:30.00Z");
# ```
# + dateTimeString - RFC 3339 timestamp (e.g., `2007-12-03T10:15:30.00Z`) as a string
# + dateTimeString - RFC 3339 timestamp (e.g., `2007-12-03T10:15:30.00Z`) as a string.
# + return - The corresponding `time:Civil` value or an error if the given `dateTimeString` is invalid
public isolated function civilFromString(string dateTimeString) returns Civil|Error {
return check externCivilFromString(dateTimeString);
Expand All @@ -167,7 +167,7 @@ public isolated function civilFromString(string dateTimeString) returns Civil|Er
# time:Civil civil = check time:civilFromString("2007-12-03T10:15:30.00Z");
# string|time:Error civilString = time:civilToString(civil);
# ```
# + civil - `time:Civil` that needs to be converted
# + civil - The `time:Civil` value to be converted
# + return - The corresponding string value or an error if the specified `time:Civil` contains invalid parameters (e.g., `month` > 12)
public isolated function civilToString(Civil civil) returns string|Error {
ZoneOffset? utcOffset = civil?.utcOffset;
Expand All @@ -194,9 +194,9 @@ public isolated function civilToString(Civil civil) returns string|Error {
# time:Utc utc = time:utcNow();
# string emailFormattedString = time:utcToEmailString(utc);
# ```
# + utc - The UTC value to be formatted
# + utc - The `time:UTC` value to be formatted
# + zh - Type of the zone value to be added
# + return - The corresponding formatted string
# + return - The corresponding formatted string value
public isolated function utcToEmailString(Utc utc, UtcZoneHandling zh = "0") returns string {
return externUtcToEmailString(utc, zh);
}
Expand All @@ -206,20 +206,20 @@ public isolated function utcToEmailString(Utc utc, UtcZoneHandling zh = "0") ret
# time:Civil|time:Error emailDateTime = time:civilFromEmailString("Wed, 10 Mar 2021 19:51:55 -0820");
# ```
# + dateTimeString - RFC 5322 formatted (e.g `Wed, 10 Mar 2021 19:51:55 -0800 (PST)`) string to be converted
# + return - The corresponding civil record or an error if the given string is incorrectly formatted.
# + return - The corresponding `time:Civil` record or an error if the given string is incorrectly formatted.
public isolated function civilFromEmailString(string dateTimeString) returns Civil|Error {
return check externCivilFromEmailString(dateTimeString);
}

# Converts a given Civil record to RFC 5322 format (e.g `Wed, 10 Mar 2021 19:51:55 -0800 (PST)`).
# Converts a given `time:Civil` record to RFC 5322 format (e.g `Wed, 10 Mar 2021 19:51:55 -0800 (PST)`).
# ```ballerina
# time:Civil civil = check time:civilFromString("2021-04-12T23:20:50.520+05:30[Asia/Colombo]");
# string|time:Error emailDateTime = time:civilToEmailString(civil, time:PREFER_ZONE_OFFSET);
# ```
# + civil - The civil record to be converted
# + civil - The `time:Civil` record to be converted
# + zoneHandling - Indicate how to handle the zone by specifying the preference whether to give preference to zone
# offset or time abbreviation. Also, this can configure to use zone offset to the execution and use time abbreviation as a comment.
# + return - RFC 5322 formatted (e.g `Wed, 10 Mar 2021 19:51:55 -0800 (PST)`) string or
# + return - The RFC 5322 formatted (e.g `Wed, 10 Mar 2021 19:51:55 -0800 (PST)`) string or
# an error if the specified `time:Civil` contains invalid parameters (e.g., `month` > 12)
public isolated function civilToEmailString(Civil civil, HeaderZoneHandling zoneHandling) returns string|Error {
int utcOffsetHours = 0;
Expand Down
20 changes: 10 additions & 10 deletions ballerina/time_types.bal
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,16 +190,16 @@ public type Zone readonly & object {
# + return - The fixed zone offset or nil
public isolated function fixedOffset() returns ZoneOffset?;

# Converts a given `Civil` value to an `Utc` timestamp based on the time zone value.
# Converts a given `time:Civil` value to an `time:Utc` timestamp based on the time zone value.
#
# + civil - `Civil` time
# + return - The corresponding `Utc` value or an error if `civil.timeAbbrev` is missing
# + civil - The `time:Civil` value to be converted
# + return - The corresponding `time:Utc` value or an error if `civil.timeAbbrev` is missing
public isolated function utcFromCivil(Civil civil) returns Utc|Error;

# Converts a given `Utc` timestamp to a `Civil` value based on the time zone value.
# Converts a given `time:Utc` timestamp to a `time:Civil` value based on the time zone value.
#
# + utc - `Utc` timestamp
# + return - The corresponding `Civil` value
# + utc - The `time:Utc` timestamp value to be converted
# + return - The corresponding `time:Civil` value
public isolated function utcToCivil(Utc utc) returns Civil;
};

Expand All @@ -210,7 +210,7 @@ public readonly class TimeZone {
# Initialize a TimeZone class using a zone ID.
#
# + zoneId - Zone ID as a string or nil to initialize a TimeZone object with the system default time zone
# + return - An error or nil
# + return - An `time:Error` if the zone ID is invalid, otherwise nil
public isolated function init(string? zoneId = ()) returns Error? {
if zoneId is string {
externTimeZoneInitWithId(self, zoneId);
Expand All @@ -228,7 +228,7 @@ public readonly class TimeZone {

# Converts a given `time:Civil` value to an `time:Utc` timestamp based on the time zone value.
#
# + civil - `time:Civil` time
# + civil - The `time:Civil` value to be converted
# + return - The corresponding `time:Utc` value or an error if `civil.timeAbbrev` is missing
public isolated function utcFromCivil(Civil civil) returns Utc|Error {
string? timeAbbrev = civil?.timeAbbrev;
Expand All @@ -243,7 +243,7 @@ public readonly class TimeZone {

# Converts a given `time:Utc` timestamp to a `time:Civil` value based on the time zone value.
#
# + utc - `time:Utc` timestamp
# + utc - The `time:Utc` timestamp value to be converted
# + return - The corresponding `time:Civil` value
public isolated function utcToCivil(Utc utc) returns Civil {
return externTimeZoneUtcToCivil(self, utc);
Expand All @@ -264,7 +264,7 @@ public isolated function loadSystemZone() returns Zone|Error {
# time:Zone? zone = time:getZone("Asia/Colombo");
# ```
# + id - Time zone ID in the format of ("Continent/City")
# + return - Corresponding ime zone object or null
# + return - Corresponding time zone object or null
public isolated function getZone(string id) returns Zone? {
TimeZone|Error timeZone = new TimeZone(id);
if timeZone is TimeZone {
Expand Down
Loading