Clarify documentation of `num_days_from_ce` methods

The new wording tries to make clearer that those methods use a 1-based
numbering scheme.

This commit also includes a couple of drive-by cosmetic changes.

src/lib.rs

@@ -890,17 +890,18 @@ pub trait Datelike: Sized {
     /// Returns `None` when the resulting value would be invalid.
     fn with_ordinal0(&self, ordinal0: u32) -> Option<Self>;
 
-    /// Returns the number of days since January 1, Year 1 (aka Day 1) in the
-    /// proleptic Gregorian calendar.
+    /// Counts the days in the proleptic Gregorian calendar, with January 1, Year 1 (CE) as day 1.
     ///
-    /// # Example:
+    /// # Examples
     ///
-    /// ~~~
+    /// ```
     /// use chrono::{NaiveDate, Datelike};
     ///
-    /// assert_eq!(NaiveDate::from_ymd(1970, 1, 1).num_days_from_ce(), 719163);
+    /// assert_eq!(NaiveDate::from_ymd(1970, 1, 1).num_days_from_ce(), 719_163);
+    /// assert_eq!(NaiveDate::from_ymd(2, 1, 1).num_days_from_ce(), 366);
+    /// assert_eq!(NaiveDate::from_ymd(1, 1, 1).num_days_from_ce(), 1);
     /// assert_eq!(NaiveDate::from_ymd(0, 1, 1).num_days_from_ce(), -365);
-    /// ~~~
+    /// ```
     fn num_days_from_ce(&self) -> i32 {
         // we know this wouldn't overflow since year is limited to 1/2^13 of i32's full range.
         let mut year = self.year() - 1;

src/naive/date.rs

@@ -330,10 +330,10 @@ impl NaiveDate {
         }
     }
 
-    /// Makes a new `NaiveDate` from the number of days since January 1, 1 (Day 1)
-    /// in the proleptic Gregorian calendar.
+    /// Makes a new `NaiveDate` from a day's number in the proleptic Gregorian calendar, with
+    /// January 1, 1 being day 1.
     ///
-    /// Panics on the out-of-range date.
+    /// Panics if the date is out of range.
     ///
     /// # Example
     ///
@@ -378,10 +378,10 @@ impl NaiveDate {
         NaiveDate::from_num_days_from_ce_opt(days).expect("out-of-range date")
     }
 
-    /// Makes a new `NaiveDate` from the number of days since January 1, 1 (Day 1)
-    /// in the proleptic Gregorian calendar.
+    /// Makes a new `NaiveDate` from a day's number in the proleptic Gregorian calendar, with
+    /// January 1, 1 being day 1.
     ///
-    /// Returns `None` on the out-of-range date.
+    /// Returns `None` if the date is out of range.
     ///
     /// # Example
     ///