From cca50147fc9336299736ded458e05a82e6f68b69 Mon Sep 17 00:00:00 2001
From: Lud <vini.lanzarini@hotmail.com>
Date: Sun, 20 May 2018 15:57:26 -0300
Subject: [PATCH 1/4] Reformatting API reference

---
 docs/en/API-reference.md | 330 +++++++++++++++------------------------
 1 file changed, 130 insertions(+), 200 deletions(-)

diff --git a/docs/en/API-reference.md b/docs/en/API-reference.md
index fc18a7484..c288d2ef7 100644
--- a/docs/en/API-reference.md
+++ b/docs/en/API-reference.md
@@ -1,213 +1,178 @@
-## API Reference
+# API Reference
 
 Instead of modifying the native `Date.prototype`, Day.js creates a wrapper for the Date object, called `Dayjs` object.
 
-`Dayjs` object is immutable, that is to say, all API operation will return a new `Dayjs` object.
-
-* [Parse](#parse)
-  * [Now](#now)
-  * [String](#string)
-  * [Unix Timestamp (milliseconds)](#unix-timestamp-milliseconds)
-  * [Date](#date)
-  * [Clone](#clone)
-  * [Validation](#validation)
-* [Get + Set](#get--set)
-  * [Year](#year)
-  * [Month](#month)
-  * [Date of Month](#date-of-month)
-  * [Day of Week](#day-of-week)
-  * [Hour](#hour)
-  * [Minute](#minute)
-  * [Second](#second)
-  * [Millisecond](#millisecond)
-  * [Set](#set)
-* [Manipulate](#manipulate)
-  * [Add](#add)
-  * [Subtract](#subtract)
-  * [Start of Time](#start-of-time)
-  * [End of Time](#end-of-time)
-* [Display](#display)
-  * [Format](#format)
-  * [Difference](#difference)
-  * [Unix Timestamp (milliseconds)](#unix-timestamp-milliseconds-1)
-  * [Unix Timestamp (seconds)](#unix-timestamp-seconds)
-  * [Days in Month](#days-in-month)
-  * [As Javascript Date](#as-javascript-date)
-  * [As Array](#as-array)
-  * [As JSON](#as-json)
-  * [As ISO 8601 String](#as-iso-8601-string)
-  * [As Object](#as-object)
-  * [As String](#as-string)
-* [Query](#query)
-  * [Is Before](#is-before)
-  * [Is Same](#is-same)
-  * [Is After](#is-after)
-  * [Is Leap Year](#is-leap-year)
-
----
-Day.js will always return a new `Dayjs` object if not specified.
-
-### Parse
-
-Simply call `dayjs()` with one of the supported input types.
-
-#### Now
-
-To get the current date and time, just call dayjs() with no parameters.
+The `Dayjs` object is immutable, that is, all API operations that change the `Dayjs` object in some way will return a new instance of it.
+
+- [API Reference](#api-reference)
+  - [Parsing](#parsing)
+    - [Constructor `.dayjs(existing?: string | number | Date | Dayjs)`](#constructor-dayjsexisting-string-number-date-dayjs)
+      - [ISO 8601 string](#iso-8601httpsenwikipediaorgwikiiso8601-string)
+      - [Unix Timestamp (milliseconds since the Unix Epoch - Jan 1 1970, 12AM UTC)](#unix-timestamp-milliseconds-since-the-unix-epoch---jan-1-1970-12am-utc)
+      - [Native Javascript Date object](#native-javascript-date-object)
+    - [Clone `.clone() | dayjs(original: Dayjs)`](#clone-clone-dayjsoriginal-dayjs)
+    - [Validation `.isValid()`](#validation-isvalid)
+  - [Get and Set](#get-and-set)
+    - [Year `.year()`](#year-year)
+    - [Month `.month()`](#month-month)
+    - [Day of the Month `.date()`](#day-of-the-month-date)
+    - [Day of the Week `.day()`](#day-of-the-week-day)
+    - [Hour `.hour()`](#hour-hour)
+    - [Minute `.minute()`](#minute-minute)
+    - [Second `.second()`](#second-second)
+    - [Millisecond `.millisecond()`](#millisecond-millisecond)
+    - [Set `.set(unit: string, value: number)`](#set-setunit-string-value-number)
+  - [Manipulating](#manipulating)
+    - [Add `.add(value: number, unit: string)`](#add-addvalue-number-unit-string)
+    - [Subtract `.subtract(value: number, unit: string)`](#subtract-subtractvalue-number-unit-string)
+    - [Start of Time `.startOf(unit: string)`](#start-of-time-startofunit-string)
+    - [End of Time `.endOf(unit: string)`](#end-of-time-endofunit-string)
+  - [Displaying](#displaying)
+    - [Format `.format(stringWithTokens: string)`](#format-formatstringwithtokens-string)
+      - [List of all available formats](#list-of-all-available-formats)
+    - [Difference `.diff(unit: string (default: 'milliseconds'))`](#difference-diffunit-string-default-milliseconds)
+    - [Unix Timestamp (milliseconds) `.valueOf()`](#unix-timestamp-milliseconds-valueof)
+    - [Unix Timestamp (seconds) `.unix()`](#unix-timestamp-seconds-unix)
+    - [Days in the Month `.daysInMonth()`](#days-in-the-month-daysinmonth)
+    - [As Javascript Date `.toDate()`](#as-javascript-date-todate)
+    - [As Array `.toArray()`](#as-array-toarray)
+    - [As JSON `.toJSON()`](#as-json-tojson)
+    - [As ISO 8601 String `.toISOString()`](#as-iso-8601-string-toisostring)
+    - [As Object `.toObject()`](#as-object-toobject)
+    - [As String `.toString()`](#as-string-tostring)
+  - [Query](#query)
+    - [Is Before `.isBefore(compared: Dayjs)`](#is-before-isbeforecompared-dayjs)
+    - [Is Same `.isSame(compared: Dayjs)`](#is-same-issamecompared-dayjs)
+    - [Is After `.isAfter(compared: Dayjs)`](#is-after-isaftercompared-dayjs)
+    - [Is Leap Year `.isLeapYear()`](#is-leap-year-isleapyear)
+
+## Parsing
+
+### Constructor `.dayjs(existing?: string | number | Date | Dayjs)`
+
+Calling it without parameters returns a fresh `Dayjs` object with the current date and time, just like `new Date()` or `moment.now()`.
 
 ```js
 dayjs();
 ```
 
-### String
+Day.js also parses other date formats.
 
-Creating from a string matches [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
+#### [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string
 
 ```js
 dayjs(String);
 dayjs('1995-12-25');
 ```
 
-### Unix Timestamp (milliseconds)
-
-Passing an integer value representing the number of milliseconds since the Unix Epoch (Jan 1 1970 12AM UTC).
+#### Unix Timestamp (milliseconds since the Unix Epoch - Jan 1 1970, 12AM UTC)
 
 ```js
 dayjs(Number);
 dayjs(1318781876406);
 ```
 
-### Date
-
-Passing a pre-existing native Javascript Date object.
+#### Native Javascript Date object
 
 ```js
 dayjs(Date);
 dayjs(new Date(2018, 8, 18));
 ```
 
-### Clone
+### Clone `.clone() | dayjs(original: Dayjs)`
 
-All `Dayjs` are immutable. If you want a copy of the object, just call `.clone()`.
-Calling dayjs() on a `Dayjs` object will also clone it.
+Returns a cloned `Dayjs` object.
 
 ```js
-dayjs(Dayjs);
 dayjs().clone();
+dayjs(Dayjs); // passing a Dayjs object to a constructor will also clone it
 ```
 
-### Validation
+### Validation `.isValid()`
 
-* returns a Boolean
-
-Check whether the `Dayjs` object considers the date invalid.
+Returns a boolean indicating whether the `Dayjs` object's date is valid.
 
 ```js
 dayjs().isValid();
 ```
 
----
-
-### Get + Set
+## Get and Set
 
-Get and set date.
+### Year `.year()`
 
-#### Year
-
-* returns a Number
-
-Get year.
+Returns a number representing the `Dayjs` object's year.
 
 ```js
 dayjs().year();
 ```
 
-#### Month
+### Month `.month()`
 
-* returns a Number
-
-Get month.
+Returns a number representing the `Dayjs` object's month.
 
 ```js
 dayjs().month();
 ```
 
-#### Date of Month
-
-* returns a Number
+### Day of the Month `.date()`
 
-Get day of the month.
+Returns a number representing the `Dayjs` object's day of the month.
 
 ```js
 dayjs().date();
 ```
 
-#### Day of Week
+### Day of the Week `.day()`
 
-* returns a Number
-
-Get day of the week.
+Returns a number representing the `Dayjs` object's day of the week
 
 ```js
 dayjs().day();
 ```
 
-#### Hour
-
-* returns a Number
+### Hour `.hour()`
 
-Get hour.
+Returns a number representing the `Dayjs` object's hour.
 
 ```js
 dayjs().hour();
 ```
 
-#### Minute
+### Minute `.minute()`
 
-* returns a Number
-
-Get minute.
+Returns a number representing the `Dayjs` object's minute.
 
 ```js
 dayjs().minute();
 ```
 
-#### Second
-
-* returns a Number
+### Second `.second()`
 
-Get second.
+Returns a number representing the `Dayjs` object's second.
 
 ```js
 dayjs().second();
 ```
 
-#### Millisecond
+### Millisecond `.millisecond()`
 
-* returns a Number
-
-Get millisecond.
+Returns a number representing the `Dayjs` object's millisecond.
 
 ```js
 dayjs().millisecond();
 ```
 
-#### Set
+### Set `.set(unit: string, value: number)`
 
-Date setter.
-Units are case insensitive
+Returns a `Dayjs` object with the applied changes.
 
 ```js
-dayjs().set((unit: String), (value: Int));
-dayjs().set('month', 3); // April
-dayjs().set('second', 30);
+dayjs().set('month', 3).set('year', 2020); // April 2020
 ```
 
----
-
-### Manipulate
+## Manipulating
 
-Once you have a `Dayjs` object, you may want to manipulate it in some way like this:
+`Dayjs` objects can be manipulated in many ways.
 
 ```js
 dayjs()
@@ -216,63 +181,55 @@ dayjs()
   .subtract(1, 'year');
 ```
 
-#### Add
+### Add `.add(value: number, unit: string)`
 
-Returns a new `Dayjs` object by adding time.
+Returns a Dayjs object.
 
 ```js
-dayjs().add((value: Number), (unit: String));
 dayjs().add(7, 'day');
 ```
 
-#### Subtract
+### Subtract `.subtract(value: number, unit: string)`
 
-Returns a new `Dayjs` object by subtracting time. exactly the same as `dayjs#add`.
+Returns a Dayjs object.
 
 ```js
-dayjs().subtract((value: Number), (unit: String));
 dayjs().subtract(7, 'year');
 ```
 
-#### Start of Time
+### Start of Time `.startOf(unit: string)`
 
-Returns a new `Dayjs` object by setting it to the start of a unit of time.
+Returns a Dayjs object set to the end of the specified unit of time.
 
 ```js
-dayjs().startOf((unit: String));
-dayjs().startOf('year');
+dayjs().startOf('week');
 ```
 
-#### End of Time
+### End of Time `.endOf(unit: string)`
 
-Returns a new `Dayjs` object by setting it to the end of a unit of time.
+Returns a Dayjs object set to the end of the specified unit of time.
 
 ```js
-dayjs().endOf((unit: String));
 dayjs().endOf('month');
+dayjs().endOf('year');
 ```
 
----
+## Displaying
 
-### Display
+### Format `.format(stringWithTokens: string)`
 
-Once parsing and manipulation are done, you need some way to display the `Dayjs` object.
+Returns a formatted string.
+To escape characters, wrap them in square or culy brackets (e.g. `[G] {um}`).
 
-#### Format
-
-* returns a String
+```js
+dayjs().format(); // "2020-04-02T08:02:17-05:00" (ISO 8601, no fractional seconds)
 
-Takes a string of tokens and replaces them with their corresponding date values.
+dayjs().format('{YYYY} MM-DDTHH:mm:ssZ[Z]'); // "{2020} 04-02T08:02:17-05:00Z"
 
-```js
-dayjs().format(String);
-dayjs().format(); // "2014-09-08T08:02:17-05:00" (ISO 8601, no fractional seconds)
-dayjs().format('{YYYY} MM-DDTHH:mm:ssZ[Z]'); // "{2014} 09-08T08:02:17-05:00Z"
+dayjs().format('DD/MM/YYYY'); // "02/04/2020"
 ```
 
-* To escape characters in string, wrap the characters in square brackets (e.g. [Z]).
-
-List of all available formats:
+#### List of all available formats
 
 | Format | Output           | Description                           |
 | ------ | ---------------- | ------------------------------------- |
@@ -300,60 +257,48 @@ List of all available formats:
 | `A`    | AM PM            |                                       |
 | `a`    | am pm            |                                       |
 
-#### Difference
+### Difference `.diff(unit: string (default: 'milliseconds'))`
 
-* returns a Number
-
-Get the difference of two `Dayjs` objects in milliseconds or another unit.
+Returns a number indicating the difference of two `Dayjs` objects in the specified unit
 
 ```js
 dayjs().diff(Dayjs, unit);
 dayjs().diff(dayjs(), 'years'); // 0
 ```
 
-#### Unix Timestamp (milliseconds)
-
-* returns a Number
+### Unix Timestamp (milliseconds) `.valueOf()`
 
-Outputs the number of milliseconds since the Unix Epoch
+Returns the number of milliseconds since the Unix Epoch.
 
 ```js
 dayjs().valueOf();
 ```
 
-#### Unix Timestamp (seconds)
+### Unix Timestamp (seconds) `.unix()`
 
-* returns a Number
-
-Outputs a Unix timestamp (the number of seconds since the Unix Epoch).
+Returns the number of seconds since the Unix Epoch.
 
 ```js
 dayjs().unix();
 ```
 
-#### Days in Month
-
-* returns a Number
+### Days in the Month `.daysInMonth()`
 
-Get the number of days in the current month.
+Returns the number of days in the `Dayjs` object's month.
 
 ```js
 dayjs().daysInMonth();
 ```
 
-#### As Javascript Date
+### As Javascript Date `.toDate()`
 
-* returns a Javascript `Date` object
-
-Get copy of the native `Date` object from `Dayjs` object.
+Returns a copy of the native `Date` object parsed from the `Dayjs` object.
 
 ```js
 dayjs().toDate();
 ```
 
-#### As Array
-
-* returns an Array
+### As Array `.toArray()`
 
 Returns an array that mirrors the parameters from new Date().
 
@@ -361,86 +306,71 @@ Returns an array that mirrors the parameters from new Date().
 dayjs().toArray(); //[2018, 8, 18, 00, 00, 00, 000];
 ```
 
-#### As JSON
+### As JSON `.toJSON()`
 
-* returns a JSON String
-
-Serializing a `Dayjs` object to JSON, will return an ISO8601 string.
+Returns an ISO8601 string.
 
 ```js
 dayjs().toJSON(); //"2018-08-08T00:00:00.000Z"
 ```
 
-#### As ISO 8601 String
-
-* returns a String
+### As ISO 8601 String `.toISOString()`
 
-Formats a string to the ISO8601 standard.
+Returns an ISO8601 string.
 
 ```js
 dayjs().toISOString();
 ```
 
-#### As Object
+### As Object `.toObject()`
 
-* returns an Object
-
-Returns an object with year, month ... millisecond.
+Returns an object with year, month, `...`, millisecond.
 
 ```js
-dayjs().toObject(); // { years:2018, months:8, date:18, hours:0, minutes:0, seconds:0, milliseconds:0}
+dayjs().toObject();
+// { years: 2018, months: 8, date: 18, hours: 0, minutes: 0, seconds: 0, milliseconds: 0 }
 ```
 
-#### As String
+### As String `.toString()`
 
-* returns a String
+Returns a string.
 
 ```js
 dayjs().toString();
 ```
 
----
-
-### Query
+## Query
 
-#### Is Before
+### Is Before `.isBefore(compared: Dayjs)`
 
-* returns a Boolean
-
-Check if a `Dayjs` object is before another `Dayjs` object.
+Returns a boolean indicating whether the `Dayjs` object's date is before a supplied `Dayjs` object's.
 
 ```js
 dayjs().isBefore(Dayjs);
 dayjs().isBefore(dayjs()); // false
 ```
 
-#### Is Same
-
-* returns a Boolean
+### Is Same `.isSame(compared: Dayjs)`
 
-Check if a `Dayjs` object is same as another `Dayjs` object.
+Returns a boolean indicating whether the `Dayjs` object's date is the same as a supplied `Dayjs` object's.
 
 ```js
 dayjs().isSame(Dayjs);
 dayjs().isSame(dayjs()); // true
 ```
 
-#### Is After
+### Is After `.isAfter(compared: Dayjs)`
 
-* returns a Boolean
-
-Check if a `Dayjs` object is after another `Dayjs` object.
+Returns a boolean indicating whether the `Dayjs` object's date is after a supplied `Dayjs` object's.
 
 ```js
 dayjs().isAfter(Dayjs);
 dayjs().isAfter(dayjs()); // false
 ```
 
-#### Is Leap Year
-
-* returns a Boolean
+### Is Leap Year `.isLeapYear()`
 
-Check if a year is a leap year.
+Returns a boolean indicating whether the `Dayjs` object's year is a leap year or not.
 
 ```js
 dayjs().isLeapYear();

From e93b566b99d4c0b820a13fdb812bfec542082dbe Mon Sep 17 00:00:00 2001
From: Lud <vini.lanzarini@hotmail.com>
Date: Sun, 20 May 2018 16:20:56 -0300
Subject: [PATCH 2/4] Added some examples

---
 docs/en/API-reference.md | 63 +++++++++++++++++++++-------------------
 1 file changed, 33 insertions(+), 30 deletions(-)

diff --git a/docs/en/API-reference.md b/docs/en/API-reference.md
index c288d2ef7..2dd73b735 100644
--- a/docs/en/API-reference.md
+++ b/docs/en/API-reference.md
@@ -61,21 +61,18 @@ Day.js also parses other date formats.
 #### [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string
 
 ```js
-dayjs(String);
 dayjs('1995-12-25');
 ```
 
 #### Unix Timestamp (milliseconds since the Unix Epoch - Jan 1 1970, 12AM UTC)
 
 ```js
-dayjs(Number);
 dayjs(1318781876406);
 ```
 
 #### Native Javascript Date object
 
 ```js
-dayjs(Date);
 dayjs(new Date(2018, 8, 18));
 ```
 
@@ -85,7 +82,7 @@ Returns a cloned `Dayjs` object.
 
 ```js
 dayjs().clone();
-dayjs(Dayjs); // passing a Dayjs object to a constructor will also clone it
+dayjs(dayjs('2019-01-25')); // passing a Dayjs object to a constructor will also clone it
 ```
 
 ### Validation `.isValid()`
@@ -167,7 +164,9 @@ dayjs().millisecond();
 Returns a `Dayjs` object with the applied changes.
 
 ```js
-dayjs().set('month', 3).set('year', 2020); // April 2020
+dayjs('2000-10-25')
+  .set('month', 3)
+  .set('year', 2020); // Sat, 25 Apr 2020 00:00:00 GMT
 ```
 
 ## Manipulating
@@ -175,10 +174,9 @@ dayjs().set('month', 3).set('year', 2020); // April 2020
 `Dayjs` objects can be manipulated in many ways.
 
 ```js
-dayjs()
-  .startOf('month')
+dayjs('2019-01-25')
   .add(1, 'day')
-  .subtract(1, 'year');
+  .subtract(1, 'year').toString(); // Fri, 26 Jan 2018 00:00:00 GMT
 ```
 
 ### Add `.add(value: number, unit: string)`
@@ -210,8 +208,7 @@ dayjs().startOf('week');
 Returns a Dayjs object set to the end of the specified unit of time.
 
 ```js
-dayjs().endOf('month');
-dayjs().endOf('year');
+dayjs().endOf('month')
 ```
 
 ## Displaying
@@ -222,11 +219,11 @@ Returns a formatted string.
 To escape characters, wrap them in square or culy brackets (e.g. `[G] {um}`).
 
 ```js
-dayjs().format(); // "2020-04-02T08:02:17-05:00" (ISO 8601, no fractional seconds)
+dayjs().format(); // current date in ISO6801, without fraction seconds e.g. '2020-04-02T08:02:17-05:00'
 
-dayjs().format('{YYYY} MM-DDTHH:mm:ssZ[Z]'); // "{2020} 04-02T08:02:17-05:00Z"
+dayjs('2019-01-25').format('{YYYY} MM-DDTHH:mm:ssZ[Z]'); // '{2019} 01-25T00:00:00-02:00Z'
 
-dayjs().format('DD/MM/YYYY'); // "02/04/2020"
+dayjs('2019-01-25').format('DD/MM/YYYY'); // '25/01/2019'
 ```
 
 #### List of all available formats
@@ -262,8 +259,11 @@ dayjs().format('DD/MM/YYYY'); // "02/04/2020"
 Returns a number indicating the difference of two `Dayjs` objects in the specified unit
 
 ```js
-dayjs().diff(Dayjs, unit);
-dayjs().diff(dayjs(), 'years'); // 0
+const date1 = dayjs('2019-01-25');
+const date2 = dayjs('2018-06-05');
+date1.diff(date2); // 20214000000 milliseconds
+date1.diff(date2, 'months'); // 7
+date1.diff(date2, 'days'); // 233
 ```
 
 ### Unix Timestamp (milliseconds) `.valueOf()`
@@ -271,7 +271,7 @@ dayjs().diff(dayjs(), 'years'); // 0
 Returns the number of milliseconds since the Unix Epoch.
 
 ```js
-dayjs().valueOf();
+dayjs('2019-01-25').valueOf(); // 1548381600000
 ```
 
 ### Unix Timestamp (seconds) `.unix()`
@@ -279,7 +279,7 @@ dayjs().valueOf();
 Returns the number of seconds since the Unix Epoch.
 
 ```js
-dayjs().unix();
+dayjs('2019-01-25').unix(); // 1548381600
 ```
 
 ### Days in the Month `.daysInMonth()`
@@ -287,7 +287,7 @@ dayjs().unix();
 Returns the number of days in the `Dayjs` object's month.
 
 ```js
-dayjs().daysInMonth();
+dayjs('2019-01-25').daysInMonth(); // 31
 ```
 
 ### As Javascript Date `.toDate()`
@@ -295,7 +295,7 @@ dayjs().daysInMonth();
 Returns a copy of the native `Date` object parsed from the `Dayjs` object.
 
 ```js
-dayjs().toDate();
+dayjs('2019-01-25').toDate();
 ```
 
 ### As Array `.toArray()`
@@ -303,7 +303,7 @@ dayjs().toDate();
 Returns an array that mirrors the parameters from new Date().
 
 ```js
-dayjs().toArray(); //[2018, 8, 18, 00, 00, 00, 000];
+dayjs('2019-01-25').toArray(); // [ 2019, 0, 25, 0, 0, 0, 0 ]
 ```
 
 ### As JSON `.toJSON()`
@@ -311,7 +311,7 @@ dayjs().toArray(); //[2018, 8, 18, 00, 00, 00, 000];
 Returns an ISO8601 string.
 
 ```js
-dayjs().toJSON(); //"2018-08-08T00:00:00.000Z"
+dayjs('2019-01-25').toJSON(); // '2019-01-25T02:00:00.000Z'
 ```
 
 ### As ISO 8601 String `.toISOString()`
@@ -319,24 +319,30 @@ dayjs().toJSON(); //"2018-08-08T00:00:00.000Z"
 Returns an ISO8601 string.
 
 ```js
-dayjs().toISOString();
+dayjs('2019-01-25').toISOString(); // '2019-01-25T02:00:00.000Z'
 ```
 
 ### As Object `.toObject()`
 
-Returns an object with year, month, `...`, millisecond.
+Returns an object with the date's properties.
 
 ```js
-dayjs().toObject();
-// { years: 2018, months: 8, date: 18, hours: 0, minutes: 0, seconds: 0, milliseconds: 0 }
+dayjs('2019-01-25').toObject();
+/* { years: 2019,
+     months: 0,
+     date: 25,
+     hours: 0,
+     minutes: 0,
+     seconds: 0,
+     milliseconds: 0 } */
 ```
 
 ### As String `.toString()`
 
-Returns a string.
+Returns a string representation of the date.
 
 ```js
-dayjs().toString();
+dayjs('2019-01-25').toString(); // 'Fri, 25 Jan 2019 02:00:00 GMT'
 ```
 
 ## Query
@@ -346,7 +352,6 @@ dayjs().toString();
 Returns a boolean indicating whether the `Dayjs` object's date is before a supplied `Dayjs` object's.
 
 ```js
-dayjs().isBefore(Dayjs);
 dayjs().isBefore(dayjs()); // false
 ```
 
@@ -355,7 +360,6 @@ dayjs().isBefore(dayjs()); // false
 Returns a boolean indicating whether the `Dayjs` object's date is the same as a supplied `Dayjs` object's.
 
 ```js
-dayjs().isSame(Dayjs);
 dayjs().isSame(dayjs()); // true
 ```
 
@@ -364,7 +368,6 @@ dayjs().isSame(dayjs()); // true
 Returns a boolean indicating whether the `Dayjs` object's date is after a supplied `Dayjs` object's.
 
 ```js
-dayjs().isAfter(Dayjs);
 dayjs().isAfter(dayjs()); // false
 ```
 

From b1e7ec35e8f8ab7311d783bc6438a1af2b45f0eb Mon Sep 17 00:00:00 2001
From: Vinicius <vini.lanzarini@hotmail.com>
Date: Sun, 20 May 2018 16:43:51 -0300
Subject: [PATCH 3/4] Add highlighting and some syntax fixed

---
 docs/en/API-reference.md | 70 ++++++++++++++++++++--------------------
 1 file changed, 35 insertions(+), 35 deletions(-)

diff --git a/docs/en/API-reference.md b/docs/en/API-reference.md
index 2dd73b735..f0b02dd99 100644
--- a/docs/en/API-reference.md
+++ b/docs/en/API-reference.md
@@ -30,7 +30,7 @@ The `Dayjs` object is immutable, that is, all API operations that change the `Da
   - [Displaying](#displaying)
     - [Format `.format(stringWithTokens: string)`](#format-formatstringwithtokens-string)
       - [List of all available formats](#list-of-all-available-formats)
-    - [Difference `.diff(unit: string (default: 'milliseconds'))`](#difference-diffunit-string-default-milliseconds)
+    - [Difference `.diff(compared: Dayjs, unit: string (default: 'milliseconds'), float?: boolean)`](#difference-diffcompared-dayjs-unit-string-default-milliseconds-float-boolean)
     - [Unix Timestamp (milliseconds) `.valueOf()`](#unix-timestamp-milliseconds-valueof)
     - [Unix Timestamp (seconds) `.unix()`](#unix-timestamp-seconds-unix)
     - [Days in the Month `.daysInMonth()`](#days-in-the-month-daysinmonth)
@@ -78,7 +78,7 @@ dayjs(new Date(2018, 8, 18));
 
 ### Clone `.clone() | dayjs(original: Dayjs)`
 
-Returns a cloned `Dayjs` object.
+Returns a cloned `Dayjs`.
 
 ```js
 dayjs().clone();
@@ -87,7 +87,7 @@ dayjs(dayjs('2019-01-25')); // passing a Dayjs object to a constructor will also
 
 ### Validation `.isValid()`
 
-Returns a boolean indicating whether the `Dayjs` object's date is valid.
+Returns a `boolean` indicating whether the `Dayjs`'s date is valid.
 
 ```js
 dayjs().isValid();
@@ -97,7 +97,7 @@ dayjs().isValid();
 
 ### Year `.year()`
 
-Returns a number representing the `Dayjs` object's year.
+Returns a `number` representing the `Dayjs`'s year.
 
 ```js
 dayjs().year();
@@ -105,7 +105,7 @@ dayjs().year();
 
 ### Month `.month()`
 
-Returns a number representing the `Dayjs` object's month.
+Returns a `number` representing the `Dayjs`'s month.
 
 ```js
 dayjs().month();
@@ -113,7 +113,7 @@ dayjs().month();
 
 ### Day of the Month `.date()`
 
-Returns a number representing the `Dayjs` object's day of the month.
+Returns a `number` representing the `Dayjs`'s day of the month.
 
 ```js
 dayjs().date();
@@ -121,7 +121,7 @@ dayjs().date();
 
 ### Day of the Week `.day()`
 
-Returns a number representing the `Dayjs` object's day of the week
+Returns a `number` representing the `Dayjs`'s day of the week
 
 ```js
 dayjs().day();
@@ -129,7 +129,7 @@ dayjs().day();
 
 ### Hour `.hour()`
 
-Returns a number representing the `Dayjs` object's hour.
+Returns a `number` representing the `Dayjs`'s hour.
 
 ```js
 dayjs().hour();
@@ -137,7 +137,7 @@ dayjs().hour();
 
 ### Minute `.minute()`
 
-Returns a number representing the `Dayjs` object's minute.
+Returns a `number` representing the `Dayjs`'s minute.
 
 ```js
 dayjs().minute();
@@ -145,7 +145,7 @@ dayjs().minute();
 
 ### Second `.second()`
 
-Returns a number representing the `Dayjs` object's second.
+Returns a `number` representing the `Dayjs`'s second.
 
 ```js
 dayjs().second();
@@ -153,7 +153,7 @@ dayjs().second();
 
 ### Millisecond `.millisecond()`
 
-Returns a number representing the `Dayjs` object's millisecond.
+Returns a `number` representing the `Dayjs`'s millisecond.
 
 ```js
 dayjs().millisecond();
@@ -161,12 +161,12 @@ dayjs().millisecond();
 
 ### Set `.set(unit: string, value: number)`
 
-Returns a `Dayjs` object with the applied changes.
+Returns a `Dayjs` with the applied changes.
 
 ```js
 dayjs('2000-10-25')
   .set('month', 3)
-  .set('year', 2020); // Sat, 25 Apr 2020 00:00:00 GMT
+  .set('year', 2020).toString(); // Sat, 25 Apr 2020 00:00:00 GMT
 ```
 
 ## Manipulating
@@ -181,7 +181,7 @@ dayjs('2019-01-25')
 
 ### Add `.add(value: number, unit: string)`
 
-Returns a Dayjs object.
+Returns a cloned `Dayjs` with a specified amount of time added.
 
 ```js
 dayjs().add(7, 'day');
@@ -189,7 +189,7 @@ dayjs().add(7, 'day');
 
 ### Subtract `.subtract(value: number, unit: string)`
 
-Returns a Dayjs object.
+Returns a cloned `Dayjs` with a specified amount of time subtracted.
 
 ```js
 dayjs().subtract(7, 'year');
@@ -197,7 +197,7 @@ dayjs().subtract(7, 'year');
 
 ### Start of Time `.startOf(unit: string)`
 
-Returns a Dayjs object set to the end of the specified unit of time.
+Returns a cloned `Dayjs` set to the end of the specified unit of time.
 
 ```js
 dayjs().startOf('week');
@@ -205,17 +205,17 @@ dayjs().startOf('week');
 
 ### End of Time `.endOf(unit: string)`
 
-Returns a Dayjs object set to the end of the specified unit of time.
+Returns a cloned `Dayjs` set to the end of the specified unit of time.
 
 ```js
-dayjs().endOf('month')
+dayjs().endOf('month');
 ```
 
 ## Displaying
 
 ### Format `.format(stringWithTokens: string)`
 
-Returns a formatted string.
+Returns a `string` with the `Dayjs`'s formatted date.
 To escape characters, wrap them in square or culy brackets (e.g. `[G] {um}`).
 
 ```js
@@ -254,21 +254,22 @@ dayjs('2019-01-25').format('DD/MM/YYYY'); // '25/01/2019'
 | `A`    | AM PM            |                                       |
 | `a`    | am pm            |                                       |
 
-### Difference `.diff(unit: string (default: 'milliseconds'))`
+### Difference `.diff(compared: Dayjs, unit: string (default: 'milliseconds'), float?: boolean)`
 
-Returns a number indicating the difference of two `Dayjs` objects in the specified unit
+Returns a `number` indicating the difference of two `Dayjs`s in the specified unit.
 
 ```js
 const date1 = dayjs('2019-01-25');
 const date2 = dayjs('2018-06-05');
-date1.diff(date2); // 20214000000 milliseconds
+date1.diff(date2); // 20214000000
 date1.diff(date2, 'months'); // 7
+date1.diff(date2, 'months', true); // 7.645161290322581
 date1.diff(date2, 'days'); // 233
 ```
 
 ### Unix Timestamp (milliseconds) `.valueOf()`
 
-Returns the number of milliseconds since the Unix Epoch.
+Returns the `number` of milliseconds since the Unix Epoch for the `Dayjs`.
 
 ```js
 dayjs('2019-01-25').valueOf(); // 1548381600000
@@ -276,7 +277,7 @@ dayjs('2019-01-25').valueOf(); // 1548381600000
 
 ### Unix Timestamp (seconds) `.unix()`
 
-Returns the number of seconds since the Unix Epoch.
+Returns the `number` of seconds since the Unix Epoch for the `Dayjs`.
 
 ```js
 dayjs('2019-01-25').unix(); // 1548381600
@@ -284,7 +285,7 @@ dayjs('2019-01-25').unix(); // 1548381600
 
 ### Days in the Month `.daysInMonth()`
 
-Returns the number of days in the `Dayjs` object's month.
+Returns the `number` of days in the `Dayjs`'s month.
 
 ```js
 dayjs('2019-01-25').daysInMonth(); // 31
@@ -300,7 +301,7 @@ dayjs('2019-01-25').toDate();
 
 ### As Array `.toArray()`
 
-Returns an array that mirrors the parameters from new Date().
+Returns an `array` that mirrors the parameters from new Date().
 
 ```js
 dayjs('2019-01-25').toArray(); // [ 2019, 0, 25, 0, 0, 0, 0 ]
@@ -308,7 +309,7 @@ dayjs('2019-01-25').toArray(); // [ 2019, 0, 25, 0, 0, 0, 0 ]
 
 ### As JSON `.toJSON()`
 
-Returns an ISO8601 string.
+Returns the `Dayjs` formatted in an ISO8601 `string`.
 
 ```js
 dayjs('2019-01-25').toJSON(); // '2019-01-25T02:00:00.000Z'
@@ -316,7 +317,7 @@ dayjs('2019-01-25').toJSON(); // '2019-01-25T02:00:00.000Z'
 
 ### As ISO 8601 String `.toISOString()`
 
-Returns an ISO8601 string.
+Returns the `Dayjs` formatted in an ISO8601 `string`.
 
 ```js
 dayjs('2019-01-25').toISOString(); // '2019-01-25T02:00:00.000Z'
@@ -324,7 +325,7 @@ dayjs('2019-01-25').toISOString(); // '2019-01-25T02:00:00.000Z'
 
 ### As Object `.toObject()`
 
-Returns an object with the date's properties.
+Returns an `object` with the date's properties.
 
 ```js
 dayjs('2019-01-25').toObject();
@@ -339,7 +340,7 @@ dayjs('2019-01-25').toObject();
 
 ### As String `.toString()`
 
-Returns a string representation of the date.
+Returns a `string` representation of the date.
 
 ```js
 dayjs('2019-01-25').toString(); // 'Fri, 25 Jan 2019 02:00:00 GMT'
@@ -349,7 +350,7 @@ dayjs('2019-01-25').toString(); // 'Fri, 25 Jan 2019 02:00:00 GMT'
 
 ### Is Before `.isBefore(compared: Dayjs)`
 
-Returns a boolean indicating whether the `Dayjs` object's date is before a supplied `Dayjs` object's.
+Returns a `boolean` indicating whether the `Dayjs`'s date is before the other supplied `Dayjs`'s.
 
 ```js
 dayjs().isBefore(dayjs()); // false
@@ -357,7 +358,7 @@ dayjs().isBefore(dayjs()); // false
 
 ### Is Same `.isSame(compared: Dayjs)`
 
-Returns a boolean indicating whether the `Dayjs` object's date is the same as a supplied `Dayjs` object's.
+Returns a `boolean` indicating whether the `Dayjs`'s date is the same as the other supplied `Dayjs`'s.
 
 ```js
 dayjs().isSame(dayjs()); // true
@@ -365,7 +366,7 @@ dayjs().isSame(dayjs()); // true
 
 ### Is After `.isAfter(compared: Dayjs)`
 
-Returns a boolean indicating whether the `Dayjs` object's date is after a supplied `Dayjs` object's.
+Returns a `boolean` indicating whether the `Dayjs`'s date is after the other supplied `Dayjs`'s.
 
 ```js
 dayjs().isAfter(dayjs()); // false
@@ -373,9 +374,8 @@ dayjs().isAfter(dayjs()); // false
 
 ### Is Leap Year `.isLeapYear()`
 
-Returns a boolean indicating whether the `Dayjs` object's year is a leap year or not.
+Returns a `boolean` indicating whether the `Dayjs`'s year is a leap year or not.
 
 ```js
-dayjs().isLeapYear();
 dayjs('2000-01-01').isLeapYear(); // true
 ```

From 0751301f9de057fa11ee471531590ebec51af103 Mon Sep 17 00:00:00 2001
From: Vinicius <vini.lanzarini@hotmail.com>
Date: Sun, 20 May 2018 16:45:05 -0300
Subject: [PATCH 4/4] Fix broken links in the TOC

---
 docs/en/API-reference.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/en/API-reference.md b/docs/en/API-reference.md
index f0b02dd99..12e0290d2 100644
--- a/docs/en/API-reference.md
+++ b/docs/en/API-reference.md
@@ -6,8 +6,8 @@ The `Dayjs` object is immutable, that is, all API operations that change the `Da
 
 - [API Reference](#api-reference)
   - [Parsing](#parsing)
-    - [Constructor `.dayjs(existing?: string | number | Date | Dayjs)`](#constructor-dayjsexisting-string-number-date-dayjs)
-      - [ISO 8601 string](#iso-8601httpsenwikipediaorgwikiiso8601-string)
+    - [Constructor `.dayjs(existing?: string | number | Date | Dayjs)`](#constructor-dayjsexisting-string--number--date--dayjs)
+      - [ISO 8601 string](#iso-8601-string)
       - [Unix Timestamp (milliseconds since the Unix Epoch - Jan 1 1970, 12AM UTC)](#unix-timestamp-milliseconds-since-the-unix-epoch---jan-1-1970-12am-utc)
       - [Native Javascript Date object](#native-javascript-date-object)
     - [Clone `.clone() | dayjs(original: Dayjs)`](#clone-clone-dayjsoriginal-dayjs)