date-and-time 2.1.2 → 2.3.0

package/PLUGINS.md

@@ -1,6 +1,6 @@
 # Plugins
 
-This library is oriented towards minimalism, so it may seem to some developers to be lacking in features. Plugin is the most realistic solution to such dissatisfaction. By importing plugins, you can extend the functionality of this library, mainly a formatter and a parser.
+This library is oriented towards minimalism, so it may seem to some developers to be lacking in features. The plugin is the most realistic solution to such dissatisfaction. By importing plugins, you can extend the functionality of this library, primarily the formatter and parser.
 
 *The formatter is used in `format()`, etc., the parser is used in `parse()`, `preparse()`, `isValid()`, etc.*
 
@@ -76,7 +76,7 @@ date.plugin('foobar');
   - It adds `timeSpan()` function that calculates the difference of two dates to the library.
 
 - [timezone](#timezone)
-  - It adds `formatTZ()` and `parseTZ()` functions that support `IANA time zone names` to the library.
+  - It adds `formatTZ()`, `parseTZ()` and `transformTZ()` that support `IANA time zone names` to the library.
 
 - [two-digit-year](#two-digit-year)
   - It adds two-digit year notation to the parser.
@@ -238,9 +238,9 @@ It adds `timeSpan()` function that calculates the difference of two dates to the
 
 #### timeSpan(date1, date2)
 
-- @param {**Date**} date1 - a Date object
-- @param {**Date**} date2 - a Date object
-- @returns {**Object**} a result object subtracting date2 from date1
+- @param {**Date**} date1 - A Date object
+- @param {**Date**} date2 - A Date object
+- @returns {**Object**} The result object of subtracting date2 from date1
 
 ```javascript
 const date = require('date-and-time');
@@ -262,11 +262,11 @@ Like `subtract()`, `timeSpan()` returns an object with functions like this:
 
 | function       | description             |
 |:---------------|:------------------------|
-| toDays         | Outputs as dates        |
-| toHours        | Outputs as hours        |
-| toMinutes      | Outputs as minutes      |
-| toSeconds      | Outputs as seconds      |
-| toMilliseconds | Outputs as milliseconds |
+| toDays         | Outputs in dates        |
+| toHours        | Outputs in hours        |
+| toMinutes      | Outputs in minutes      |
+| toSeconds      | Outputs in seconds      |
+| toMilliseconds | Outputs in milliseconds |
 
 In these functions can be available some tokens to format the calculation result. Here are the tokens and their meanings:
 
@@ -290,25 +290,35 @@ In these functions can be available some tokens to format the calculation result
 
 ### timezone
 
-It adds `formatTZ()` and `parseTZ()` functions that support `IANA time zone names` (`America/Los_Angeles`, `Asia/Tokyo`, and so on) to the library.
+It adds `formatTZ()`, `parseTZ()` and `transformTZ()` that support `IANA time zone names` (`America/Los_Angeles`, `Asia/Tokyo`, and so on) to the library.
 
 #### formatTZ(dateObj, arg[, timeZone])
 
-- @param {**Date**} dateObj - a Date object
-- @param {**string|Array.\<string\>**} arg - a format string or its compiled object
-- @param {**string**} [timeZone] - output as this time zone
-- @returns {**string**} a formatted string
+- @param {**Date**} dateObj - A Date object
+- @param {**string|Array.\<string\>**} arg - A format string or its compiled object
+- @param {**string**} [timeZone] - Output as this time zone
+- @returns {**string**} A formatted string
 
-The `formatTZ()` is upward compatible with `format()`. Tokens available here are the same as for the `format()`.  If the `timeZone` is omitted, it output the date string with local time zone.
+`formatTZ()` is upward compatible with `format()`. Tokens available for `arg` are the same as those for `format()`. If `timeZone` is omitted, this function assumes `timeZone` to be a local time zone and outputs a string. This means that the result is the same as when `format()` is used.
 
 #### parseTZ(dateString, arg[, timeZone])
 
-- @param {**string**} dateString - a date string
-- @param {**string|Array.\<string\>**} arg - a format string or its compiled object
-- @param {**string**} [timeZone] - input as this time zone
-- @returns {**Date**} a constructed date
+- @param {**string**} dateString - A date and time string
+- @param {**string|Array.\<string\>**} arg - A format string or its compiled object
+- @param {**string**} [timeZone] - Input as this time zone
+- @returns {**Date**} A Date object
 
-The `parseTZ()` is upward compatible with `parse()`. Tokens available here are the same as for the `parse()`. If the `timeZone` is omitted, the time zone of the date string is assumed to be local time zone.
+`parseTZ()` is upward compatible with `parse()`. Tokens available for `arg` are the same as those for `parse()`. `timeZone` in this function is used as supplemental information. if `dateString` contains a time zone offset value (i.e. -0800, +0900), `timeZone` is not be used. If `dateString` doesn't contain a time zone offset value and `timeZone` is omitted, this function assumes `timeZone` to be a local time zone. This means that the result is the same as when `parse()` is used.
+
+#### transformTZ(dateString, arg1, arg2[, timeZone])
+
+- @param {**string**} dateString - A date and time string
+- @param {**string|Array.\<string\>**} arg1 - A format string before transformation or its compiled object
+- @param {**string|Array.\<string\>**} arg2 - A format string after transformation or its compiled object
+- @param {**string**} [timeZone] - Output as this time zone
+- @returns {**string**} A formatted string
+
+`transformTZ()` is upward compatible with `transform()`. `dateString` must itself contain a time zone offset value (i.e. -0800, +0900), otherwise this function assumes it is a local time zone. Tokens available for `arg1` are the same as those for `parse()`, also tokens available for `arg2` are the same as those for `format()`. `timeZone` is a `IANA time zone names`, which is required to output a new formatted string. If it is omitted, this function assumes `timeZone` to be a local time zone. This means that the result is the same as when `transform()` is used.
 
 ```javascript
 const date = require('date-and-time');
@@ -329,16 +339,22 @@ date.parseTZ('Sep 25 2021 4:00:00', 'MMM D YYYY H:mm:ss', 'Pacific/Honolulu');
 
 // Parses the date string assuming that the time zone is "Europe/London" (UTC+0100).
 date.parseTZ('Sep 25 2021 4:00:00', 'MMM D YYYY H:mm:ss', 'Europe/London');  // 2021-09-25T03:00:00.000Z
+
+// Transforms the date string from EST (Eastern Standard Time) to PDT (Pacific Daylight Time).
+date.transformTZ('2021-11-07T03:59:59 UTC-0500', 'YYYY-MM-DD[T]HH:mm:ss [UTC]Z', 'MMMM D YYYY H:mm:ss UTC[Z]', 'America/Los_Angeles'); // November 7 2021 1:59:59 UTC-0700
+
+// Transforms the date string from PDT(Pacific Daylight Time) to JST (Japan Standard Time).
+date.transformTZ('2021-03-14T03:00:00 UTC-0700', 'YYYY-MM-DD[T]HH:mm:ss [UTC]Z', 'MMMM D YYYY H:mm:ss UTC[Z]', 'Asia/Tokyo');   // March 14 2021 19:00:00 UTC+0900
 ```
 
 #### Caveats
 
 - This plugin uses the [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) object to parse `IANA time zone names`. Note that if you use this plugin in older browsers, this may **NOT** be supported there. At least it does not work  in IE.
-- If you don't need to use `IANA time zone names`, you should not use this plugin for performance reasons. The `format()` and the `parse()` are enough.
+- If you don't need to use `IANA time zone names`, you should not use this plugin for performance reasons. Recommended to use `format()` and `parse()`.
 
 #### Start of DST (Daylight Saving Time)
 
-For example, in the US, when local standard time is about to reach Sunday, 14 March 2021, `02:00:00` clocks are turned `forward` 1 hour to Sunday, 14 March 2021, `03:00:00` local daylight time instead. Thus, there is no `02:00:00` to `02:59:59` on 14 March 2021. In such edge cases, the `parseTZ()` will parse like this:
+For example, in the US, when local standard time is about to reach Sunday, 14 March 2021, `02:00:00` clocks are turned `forward` 1 hour to Sunday, 14 March 2021, `03:00:00` local daylight time instead. Thus there is no `02:00:00` to `02:59:59` on 14 March 2021. In such edge cases, `parseTZ()` will parse like this:
 
 ```javascript
 date.parseTZ('Mar 14 2021 1:59:59', 'MMM D YYYY H:mm:ss', 'America/Los_Angeles'); // => 2021-03-14T09:59:59Z
@@ -349,16 +365,16 @@ date.parseTZ('Mar 14 2021 3:00:00', 'MMM D YYYY H:mm:ss', 'America/Los_Angeles')
 
 #### End of DST
 
-Also, when local daylight time is about to reach Sunday, 7 November 2021, `02:00:00` clocks are turned `backward` 1 hour to Sunday, 7 November 2021, `01:00:00` local standard time instead. Thus, `01:00:00` to `01:59:59` on November 7 2021 is repeated twice. Since there are two possible times between them, DST or not, the `parseTZ()` assumes that the time is former to make the result unique:
+Also, when local daylight time is about to reach Sunday, 7 November 2021, `02:00:00` clocks are turned `backward` 1 hour to Sunday, 7 November 2021, `01:00:00` local standard time instead. Thus `01:00:00` to `01:59:59` on November 7 2021 is repeated twice. Since there are two possible times here, `parseTZ()` assumes that the time is the former (DST) in order to make the result unique:
 
 ```javascript
-// The parseTZ() assumes that this time is DST.
+// This time is DST or PST? The parseTZ() always assumes that it is DST.
 date.parseTZ('Nov 7 2021 1:59:59', 'MMM D YYYY H:mm:ss', 'America/Los_Angeles');  // => 2021-11-07T08:59:59Z
 // This time is already PST.
 date.parseTZ('Nov 7 2021 2:00:00', 'MMM D YYYY H:mm:ss', 'America/Los_Angeles');  // => 2021-11-07T10:00:00Z
 ```
 
-At the first example above, if you want the parser to parse the time as PST (Pacific Standard Time), use the `parse()` with a time offset instead:
+In the first example above, if you want `parseTZ()` to parse the time as PST, you need to pass a date string containing the time zone offset value. In this case, it is better to use `parse()` instead:
 
 ```javascript
 date.parse('Nov 7 2021 1:59:59 -0800', 'MMM D YYYY H:mm:ss Z'); // => 2021-11-07T09:59:59Z

package/README.md

@@ -24,25 +24,16 @@ npm i date-and-time
 
 ## Recent Changes
 
-- 2.1.2
-  - Fixed an issue that the lib's validation logic would condider an error when a timezone offset value of a datetime string was greater then +12 hours.
+- 2.3.0
+  - TypeScript support.
+  - Fixed an issue where `parseTZ()` in timezone plugin could return `NaN` instead of `Invalid Date` if parsing failed.
 
-- 2.1.1
-  - Updated dev dependencies to resolve vulnerability.
+- 2.2.1
+  - Fixed an issue where `parse()` would treat a date and time string containing a UTC time zone (i.e. +0000) as a local time zone when parsing.
 
-- 2.1.0
-  - Fixed an issue that the lib's functions assigned to variables using ES6 destructuring assignment cause an error.
-
-  ```javascript
-  // Destructuring assignment
-  const { format, parse } = require('date-and-time');
-
-  // These used to be errors in 2.0.x.
-  format(new Date(), 'MMM DD YYYY');
-  parse('Jan 11 2022', 'MMM DD YYYY');
-  ```
-
-  - Added Swedish support.
+- 2.2.0
+  - Added `tranformTZ()` to `timezone` plugin. See [PLUGINS.md](./PLUGINS.md) for details.
+  - Added `ZZ` token to support time zone values with colon like `-08:00` `+09:00` to `format()` and `parse()`.
 
 ## Usage
 
@@ -69,32 +60,34 @@ import date from '/path/to/date-and-time.es.min.js';
 - Older browser:
 
 ```html
-<script src="/path/to/date-and-time.min.js"></script>
+<script src="/path/to/date-and-time.min.js">
+// You will be able to access the global variable `date`.
+</script>
 ```
 
 ### Note
 
-- If you want to use ES Modules in Node.js without a transpiler, you need to add `"type": "module"` in your `package.json` or change your file extension from `.js` to `.mjs`.
+- If you want to use ES Modules in Node.js without the transpiler, you need to add `"type": "module"` in your `package.json` or change your file extension from `.js` to `.mjs`.
 
 ## API
 
 - [format](#formatdateobj-arg-utc)
-  - Formatting a Date and Time (Date -> String)
+  - Formatting date and time objects (Date -> String)
 
 - [parse](#parsedatestring-arg-utc)
-  - Parsing a Date and Time string (String -> Date)
+  - Parsing date and time strings (String -> Date)
 
 - [compile](#compileformatstring)
-  - Compiling a format string
+  - Compiling format strings
 
 - [preparse](#preparsedatestring-arg)
-  - Pre-parsing a Date and Time string
+  - Pre-parsing date and time strings
 
 - [isValid](#isvalidarg1-arg2)
-  - Validation
+  - Date and time string validation
 
 - [transform](#transformdatestring-arg1-arg2-utc)
-  - Transforming a Date and Time string (String -> String)
+  - Format transformation of date and time strings (String -> String)
 
 - [addYears](#addyearsdateobj-years)
   - Adding years
@@ -118,29 +111,29 @@ import date from '/path/to/date-and-time.es.min.js';
   - Adding milliseconds
 
 - [subtract](#subtractdate1-date2)
-  - Subtracting two dates
+  - Subtracting two dates (date1 - date2)
 
 - [isLeapYear](#isleapyeary)
-  - Whether year is leap year
+  - Whether a year is a leap year
 
 - [isSameDay](#issamedaydate1-date2)
   - Comparison of two dates
 
-- [locale](#localecode-locale)
-  - Changing the locale or defining new locales
+- [locale](#localelocale)
+  - Changing locales
 
 - [extend](#extendextension)
-  - Feature extension
+  - Functional extension
 
-- [plugin](#pluginname-plugin)
-  - Importing or defining plugins
+- [plugin](#pluginplugin)
+  - Importing plugins
 
 ### format(dateObj, arg[, utc])
 
-- @param {**Date**} dateObj - a Date object
-- @param {**string|Array.\<string\>**} arg - a format string or its compiled object
-- @param {**boolean**} [utc] - output as UTC
-- @returns {**string**} a formatted string
+- @param {**Date**} dateObj - A Date object
+- @param {**string|Array.\<string\>**} arg - A format string or its compiled object
+- @param {**boolean**} [utc] - Output as UTC
+- @returns {**string**} A formatted string
 
 ```javascript
 const now = new Date();
@@ -181,7 +174,8 @@ Available tokens and their meanings are as follows:
 | SSS   | millisecond (high accuracy)          | 753, 022           |
 | SS    | millisecond (middle accuracy)        | 75, 02             |
 | S     | millisecond (low accuracy)           | 7, 0               |
-| Z     | timezone offset                      | +0100, -0800       |
+| Z     | time zone offset value               | +0100, -0800       |
+| ZZ    | time zone offset value with colon    | +01:00, -08:00     |
 
 You can also use the following tokens by importing plugins. See [PLUGINS.md](./PLUGINS.md) for details.
 
@@ -203,7 +197,7 @@ date.format(new Date(), '[DD-[MM]-YYYY]');  // => 'DD-[MM]-YYYY'
 
 #### Note 2. Output as UTC
 
-This function usually outputs a local date-time string. Set to true the `utc` option (the 3rd parameter) if you would like to get a UTC date-time string.
+This function usually outputs a local date and time string. Set to true the `utc` option (the 3rd parameter) if you would like to get a UTC date and time string.
 
 ```javascript
 date.format(new Date(), 'hh:mm A [GMT]Z');          // => '11:14 PM GMT-0800'
@@ -216,10 +210,10 @@ You can also define your own tokens. See [EXTEND.md](./EXTEND.md) for details.
 
 ### parse(dateString, arg[, utc])
 
-- @param {**string**} dateString - a date string
-- @param {**string|Array.\<string\>**} arg - a format string or its compiled object
-- @param {**boolean**} [utc] - input as UTC
-- @returns {**Date**} a constructed date
+- @param {**string**} dateString - A date and time string
+- @param {**string|Array.\<string\>**} arg - A format string or its compiled object
+- @param {**boolean**} [utc] - Input as UTC
+- @returns {**Date**} A Date object
 
 ```javascript
 date.parse('2015/01/02 23:14:05', 'YYYY/MM/DD HH:mm:ss');   // => Jan 2 2015 23:14:05 GMT-0800
@@ -255,7 +249,8 @@ Available tokens and their meanings are as follows:
 | SSS    | millisecond (high accuracy)          | 753, 022                    |
 | SS     | millisecond (middle accuracy)        | 75, 02                      |
 | S      | millisecond (low accuracy)           | 7, 0                        |
-| Z      | timezone offset                      | +0100, -0800                |
+| Z      | time zone offset value               | +0100, -0800                |
+| ZZ     | time zone offset value with colon    | +01:00, -08:00              |
 
 You can also use the following tokens by importing plugins. See [PLUGINS.md](./PLUGINS.md) for details.
 
@@ -286,7 +281,7 @@ if (isNaN(today)) {
 
 #### Note 2. Input as UTC
 
-This function usually assumes the `dateString` is a local date-time. Set to true the `utc` option (the 3rd parameter) if it is a UTC date-time.
+This function assumes the `dateString` is a local datea and time unless it contains a time zone offset value. Set to true the `utc` option (the 3rd parameter) if it is a UTC date and time.
 
 ```javascript
 date.parse('11:14:05 PM', 'hh:mm:ss A');          // => Jan 1 1970 23:14:05 GMT-0800
@@ -325,7 +320,7 @@ date.parse('11:14:05 PM', 'hh:mm:ss A');    // => Jan 1 1970 23:14:05 GMT-0800
 
 #### Note 6. Token disablement
 
-Use square brackets `[]` if a date-time string includes some token characters. Tokens inside square brackets in the `formatString` will be interpreted as normal characters:
+Use square brackets `[]` if a datea and time string includes some token characters. Tokens inside square brackets in the `formatString` will be interpreted as normal characters:
 
 ```javascript
 date.parse('12 hours 34 minutes', 'HH hours mm minutes');       // => Invalid Date
@@ -353,8 +348,8 @@ date.parse('2015/01/02 11:14:05', 'YYYY/MM/DD...');   // => Jan 2 2015 00:00:00
 
 ### compile(formatString)
 
-- @param {**string**} formatString - a format string
-- @returns {**Array.\<string\>**} a compiled object
+- @param {**string**} formatString - A format string
+- @returns {**Array.\<string\>**} A compiled object
 
 If you are going to execute the `format()`, the `parse()` or the `isValid()` so many times with one string format, recommended to precompile and reuse it for performance.
 
@@ -370,9 +365,9 @@ If you are going to execute the `format()`, the `parse()` or the `isValid()` so
 
 ### preparse(dateString, arg)
 
-- @param {**string**} dateString - a date string
-- @param {**string|Array.\<string\>**} arg - a format string or its compiled object
-- @returns {**Object**} a date structure
+- @param {**string**} dateString - A date and time string
+- @param {**string|Array.\<string\>**} arg - A format string or its compiled object
+- @returns {**Object**} A pre-parsed result object
 
 This function takes exactly the same parameters with the `parse()`, but returns a date structure as follows unlike that:
 
@@ -400,9 +395,9 @@ This date structure provides a parsing result. You will be able to tell from it
 
 ### isValid(arg1[, arg2])
 
-- @param {**Object|string**} arg1 - a date structure or a date string
-- @param {**string|Array.\<string\>**} [arg2] - a format string or its compiled object
-- @returns {**boolean**} whether the date string is a valid date
+- @param {**Object|string**} arg1 - A pre-parsed result object or a date and time string
+- @param {**string|Array.\<string\>**} [arg2] - A format string or its compiled object
+- @returns {**boolean**} Whether the date and time string is a valid date and time
 
 This function takes either exactly the same parameters with the `parse()` or a date structure which the `preparse()` returns, evaluates the validity of them.
 
@@ -418,11 +413,11 @@ date.isValid(result);   // => true
 
 ### transform(dateString, arg1, arg2[, utc])
 
-- @param {**string**} dateString - a date string
-- @param {**string|Array.\<string\>**} arg1 - a format string or its compiled object
-- @param {**string|Array.\<string\>**} arg2 - a transformed format string or its compiled object
-- @param {**boolean**} [utc] - output as UTC
-- @returns {**string**} a formatted string
+- @param {**string**} dateString - A date and time string
+- @param {**string|Array.\<string\>**} arg1 - A format string or its compiled object before transformation
+- @param {**string|Array.\<string\>**} arg2 - A format string or its compiled object after transformation
+- @param {**boolean**} [utc] - Output as UTC
+- @returns {**string**} A formatted string
 
 This function transforms the format of a date string. The 2nd parameter, `arg1`, is the format string of it. Available token list is equal to the `parse()`'s. The 3rd parameter, `arg2`, is the transformed format string. Available token list is equal to the `format()`'s.
 
@@ -436,9 +431,9 @@ date.transform('13:05', 'HH:mm', 'hh:mm A');
 
 ### addYears(dateObj, years)
 
-- @param {**Date**} dateObj - a Date object
-- @param {**number**} years - number of years to add
-- @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - A Date object
+- @param {**number**} years - Number of years to add
+- @returns {**Date**} The Date object after adding the value
 
 ```javascript
 const now = new Date();
@@ -447,9 +442,9 @@ const next_year = date.addYears(now, 1);
 
 ### addMonths(dateObj, months)
 
-- @param {**Date**} dateObj - a Date object
-- @param {**number**} months - number of months to add
-- @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - A Date object
+- @param {**number**} months - Number of months to add
+- @returns {**Date**} The Date object after adding the value
 
 ```javascript
 const now = new Date();
@@ -458,9 +453,9 @@ const next_month = date.addMonths(now, 1);
 
 ### addDays(dateObj, days)
 
-- @param {**Date**} dateObj - a Date object
-- @param {**number**} days - number of days to add
-- @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - A Date object
+- @param {**number**} days - Number of days to add
+- @returns {**Date**} The Date object after adding the value
 
 ```javascript
 const now = new Date();
@@ -469,9 +464,9 @@ const yesterday = date.addDays(now, -1);
 
 ### addHours(dateObj, hours)
 
-- @param {**Date**} dateObj - a Date object
-- @param {**number**} hours - number of hours to add
-- @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - A Date object
+- @param {**number**} hours - Number of hours to add
+- @returns {**Date**} The Date object after adding the value
 
 ```javascript
 const now = new Date();
@@ -480,9 +475,9 @@ const an_hour_ago = date.addHours(now, -1);
 
 ### addMinutes(dateObj, minutes)
 
-- @param {**Date**} dateObj - a Date object
-- @param {**number**} minutes - number of minutes to add
-- @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - A Date object
+- @param {**number**} minutes - Number of minutes to add
+- @returns {**Date**} The Date object after adding the value
 
 ```javascript
 const now = new Date();
@@ -491,9 +486,9 @@ const two_minutes_later = date.addMinutes(now, 2);
 
 ### addSeconds(dateObj, seconds)
 
-- @param {**Date**} dateObj - a Date object
-- @param {**number**} seconds - number of seconds to add
-- @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - A Date object
+- @param {**number**} seconds - Number of seconds to add
+- @returns {**Date**} The Date object after adding the value
 
 ```javascript
 const now = new Date();
@@ -502,9 +497,9 @@ const three_seconds_ago = date.addSeconds(now, -3);
 
 ### addMilliseconds(dateObj, milliseconds)
 
-- @param {**Date**} dateObj - a Date object
-- @param {**number**} milliseconds - number of milliseconds to add
-- @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - A Date object
+- @param {**number**} milliseconds - Number of milliseconds to add
+- @returns {**Date**} The Date object after adding the value
 
 ```javascript
 const now = new Date();
@@ -513,9 +508,9 @@ const a_millisecond_later = date.addMilliseconds(now, 1);
 
 ### subtract(date1, date2)
 
-- @param {**Date**} date1 - a Date object
-- @param {**Date**} date2 - a Date object
-- @returns {**Object**} a result object subtracting date2 from date1
+- @param {**Date**} date1 - A Date object
+- @param {**Date**} date2 - A Date object
+- @returns {**Object**} The result object of subtracting date2 from date1
 
 ```javascript
 const today = new Date(2015, 0, 2);
@@ -530,8 +525,8 @@ date.subtract(today, yesterday).toMilliseconds();   // => 86400000
 
 ### isLeapYear(y)
 
-- @param {**number**} y - year
-- @returns {**boolean**} whether year is leap year
+- @param {**number**} y - A year to check
+- @returns {**boolean**} Whether the year is a leap year
 
 ```javascript
 date.isLeapYear(2015);  // => false
@@ -540,9 +535,9 @@ date.isLeapYear(2012);  // => true
 
 ### isSameDay(date1, date2)
 
-- @param {**Date**} date1 - a Date object
-- @param {**Date**} date2 - a Date object
-- @returns {**boolean**} whether the two dates are the same day (time is ignored)
+- @param {**Date**} date1 - A Date object
+- @param {**Date**} date2 - A Date object
+- @returns {**boolean**} Whether the two dates are the same day (time is ignored)
 
 ```javascript
 const date1 = new Date(2017, 0, 2, 0);          // Jan 2 2017 00:00:00
@@ -552,11 +547,10 @@ date.isSameDay(date1, date2);   // => true
 date.isSameDay(date1, date3);   // => false
 ```
 
-### locale([code[, locale]])
+### locale([locale])
 
-- @param {**Function|string**} [code] - locale installer | language code
-- @param {**Object**} [locale] - locale definition
-- @returns {**string**} current language code
+- @param {**Function|string**} [locale] - A locale installer or language code
+- @returns {**string**} The current language code
 
 It returns the current language code if called without any parameters.
 
@@ -576,15 +570,14 @@ See [LOCALE.md](./LOCALE.md) for details.
 
 ### extend(extension)
 
-- @param {**Object**} extension - extension object
+- @param {**Object**} extension - An extension object
 - @returns {**void**}
 
 It extends this library. See [EXTEND.md](./EXTEND.md) for details.
 
-### plugin(name[, plugin])
+### plugin(plugin)
 
-- @param {**Function|string**} name - plugin installer | plugin name
-- @param {**Object**} [plugin] - plugin object
+- @param {**Function|string**} plugin - A plugin installer or plugin name
 - @returns {**void**}
 
 Plugin is a named extension object. By installing predefined plugins, you can easily extend this library. See [PLUGINS.md](./PLUGINS.md) for details.