Add some examples to Utc::now and Local::now

src/offset/local/mod.rs

@@ -113,7 +113,33 @@ impl Local {
         Local::now().date()
     }
 
-    /// Returns a `DateTime` which corresponds to the current date and time.
+    /// Returns a `DateTime<Local>` which corresponds to the current date, time and offset from
+    /// UTC.
+    ///
+    /// See also the similar [`Utc::now()`] which returns `DateTime<Utc>`, i.e. without the local
+    /// offset.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # #![allow(unused_variables)]
+    /// # use chrono::{DateTime, FixedOffset, Local};
+    /// // Current local time
+    /// let now = Local::now();
+    ///
+    /// // Current local date
+    /// let today = now.date_naive();
+    ///
+    /// // Current local time, converted to `DateTime<FixedOffset>`
+    /// let now_fixed_offset = Local::now().fixed_offset();
+    /// // or
+    /// let now_fixed_offset: DateTime<FixedOffset> = Local::now().into();
+    ///
+    /// // Current time in some timezone (let's use +05:00)
+    /// // Note that it is usually more efficient to use `Utc::now` for this use case.
+    /// let offset = FixedOffset::east_opt(5 * 60 * 60).unwrap();
+    /// let now_with_offset = Local::now().with_timezone(&offset);
+    /// ```
     pub fn now() -> DateTime<Local> {
         Utc::now().with_timezone(&Local)
     }

src/offset/utc.rs

@@ -59,7 +59,28 @@ impl Utc {
         Utc::now().date()
     }
 
-    /// Returns a `DateTime` which corresponds to the current date and time.
+    /// Returns a `DateTime<Utc>` which corresponds to the current date and time in UTC.
+    ///
+    /// See also the similar [`Local::now()`] which returns `DateTime<Local>`, i.e. the local date
+    /// and time including offset from UTC.
+    ///
+    /// [`Local::now()`]: crate::Local::now
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # #![allow(unused_variables)]
+    /// # use chrono::{FixedOffset, Utc};
+    /// // Current time in UTC
+    /// let now_utc = Utc::now();
+    ///
+    /// // Current date in UTC
+    /// let today_utc = now_utc.date_naive();
+    ///
+    /// // Current time in some timezone (let's use +05:00)
+    /// let offset = FixedOffset::east_opt(5 * 60 * 60).unwrap();
+    /// let now_with_offset = Utc::now().with_timezone(&offset);
+    /// ```
     #[cfg(not(all(
         target_arch = "wasm32",
         feature = "wasmbind",