Added usage statements to DateTime.pod

Author: dha

lib/Type/DateTime.pod

@@ -38,6 +38,8 @@ say $dt.in-timezone(-8 * 3600);     # 2015-11-21T08:01:00-0800
 
 =head2 method new
 
+Defined as:
+
     multi method new(Int :$year!, Int :$month, Int :$day,
                      Int :$hour, Int :$minute, :$second
                      :$timezone, :&formatter)
@@ -48,6 +50,16 @@ say $dt.in-timezone(-8 * 3600);     # 2015-11-21T08:01:00-0800
     multi method new(Int:D $posix,  :$timezone=0, :&formatter)
     multi method new(Str:D $format, :$timezone=0, :&formatter)
 
+Usage:
+
+    $datetime = DateTime.new(YEAR, MONTH?, DAY?, HOUR? MINUTE?, SECOND?,
+    TIMEZONE?, FORMATTER?)
+    $datetime = DateTime.new(DATE, HOUR?, MINUTE?, SECOND?, TIMEZONE?,
+    FORMATTER?)
+    $datetime = DateTime.new(INSTANT, TIMEZONE?, FORMATTER?)
+    $datetime = DateTime.new(TIMESTAMP, TIMEZONE?, FORMATTER?)
+    $datetime = DateTime.new(FORMAT, TIMEZONE?, FORMATTER?)
+
 Creates a new C<DateTime> object. One option for creating a new DateTime object
 is from the components (year, month, day, hour, ...) separately. Another is to
 pass a L<Date|/type/Date> object for the date component, and specify the time
@@ -64,16 +76,29 @@ L<X::DateTime:TimezoneClash> is thrown.
 
 =head2 method now
 
+Defined as:
+
     method now(:$timezone=*$TZ, &formatter) returns DateTime:D
 
+Usage:
+
+    DateTime.now
+
 Creates a new C<DateTime> object from the current system time, optionally with
 a different timezone than the default attached.
 
 =head2 method clone
 
+Defined as:
+
     method clone(:$year, :$month, :$day, :$hour, :$minute, :$second,
                  :$timezone, :&formatter)
 
+Usage:
+
+    DATETIME.clone(YEAR, MONTH, DATE, HOUR, MINUTE, SECOND, TIMEZONE,
+    FORMATTER)
+
 Creates a new C<DateTime> object based on the invocant, but with the given
 arguments overriding the values from the invocant.
 
@@ -87,75 +112,129 @@ Note that this can lead to invalid dates in some circumstances:
 
 =head2 method hour
 
+Defined as:
+
     method hour(DateTime:D:) returns Int:D
 
+Usage:
+
+   DATETIME.hour
+
 Returns the hour component.
 
     say DateTime.new('2012-02-29T12:34:56Z').hour;      # 12
 
 =head2 method minute
 
+Defined as:
+
     method minute(DateTime:D:) returns Int:D
 
+Usage:
+
+    DATETIME.minute
+
 Returns the minute component.
 
     say DateTime.new('2012-02-29T12:34:56Z').minute;     # 34
 
 =head2 method second
 
+Defined as:
+
     method second(DateTime:D:)
 
+Usage:
+
+    DATETIME.second
+
 Returns the second component, including potentially fractional seconds.
 
     say DateTime.new('2012-02-29T12:34:56Z').second;     # 56
 
 =head2 method whole-second
 
+Defined as:
+
     method whole-second(DateTime:D:)
 
+Usage:
+
+    DATETIME.whole-second
+
 Returns the second component, rounded down to an L<Int|/type/Int>.
 
     say DateTime.new('2012-02-29T12:34:56Z').whole-second;      # 56
 
 =head2 method timezone
 
+Defined as:
+
     method timezone(DateTime:D:) returns Int:D
 
+Usage:
+
+    DATETIME.timezone
+
 Returns the time zone in seconds as an offset from UTC.
 
     say DateTime.new('2015-12-24T12:23:00+0200').timezone;      # 7200
 
 =head2 method offset
 
+Defined as:
+
     method offset(DateTime:D:) returns Int:D
 
+Usage:
+
+    DATETIME.offset
+
 Returns the time zone in seconds as an offset from UTC. This is an alias for
 L<#method timezone>.
 
     say DateTime.new('2015-12-24T12:23:00+0200').offset;        # 7200
 
 =head2 method offset-in-minutes
 
+Defined as:
+
     method offset-in-minutes(DateTime:D:) returns Real:D
 
+Usage:
+
+    DATETIME.offset-in-minutes
+
 Returns the time zone in minutes as an offset from UTC.
 
     say DateTime.new('2015-12-24T12:23:00+0200').offset-in-minutes;
             # 120
 
 =head2 method offset-in-hours
 
+Defined as:
+
     method offset-in-hours(DateTime:D:) returns Real:D
 
+Usage:
+
+    DATETIME.offset-in-hours
+
 Returns the time zone in hours as an offset from UTC.
 
     say DateTime.new('2015-12-24T12:23:00+0200').offset-in-hours;
             # 2
 
 =head2 method formatter
 
+Defined as:
+
     method formatter(DateTime:D:)
 
+Usage:
+
+    DATETIME.formatter
+
 Returns the formatting function which is used for conversion to
 L<Str|/type/Str>. If none was provided at object construction, a
 default formatter is used which produces an ISO 8601 timestamp.
@@ -165,29 +244,53 @@ only argument.
 
 =head2 method Str
 
+Defined as:
+
     method Str(DateTime:D:) returns Str:D
 
+Usage:
+
+    DATETIME.Str
+
 Returns a string representation of the invocant, as done by
 L<the formatter|#method formatter>.
 
 =head2 method Instant
 
+Defined as:
+
     method Instant(DateTime:D:) returns Instant:D
 
+Usage:
+
+    DATETIME.Instant
+
 Returns an L<Instant|/type/Instant> object based on the invocant.
 
 =head2 method posix
 
+Defined as:
+
     method posix(DateTime:D: $ignore-timezone = False) returns Int:D
 
+Usage:
+
+    DATETIME.posix
+
 Returns the date and time as a POSIX/UNIX timestamp.
 
     say DateTime.new('2015-12-24T12:23:00Z').posix;     # 1450959780
 
 =head2 method later
 
+Defined as:
+
     method later(DateTime:D: *%unit)
 
+Usage:
+
+    DATETIME.later(DELTA)
+
 Returns a DateTime object based on the current one, but with a time delta
 applied. The time delta can be passed as a named argument where the argument
 name is the unit.
@@ -211,15 +314,27 @@ that.
 
 =head2 method earlier
 
+Defined as:
+
     method earlier(DateTime:D: *%unit)
 
+Usage:
+
+    DATETIME.earlier(DELTA)
+
 Returns a DateTime object based on the current one, but with a time delta
 towards the past applied. See L<#method later> for usage.
 
 =head2 method truncated-to
 
+Defined as:
+
     method truncated-to(DateTime:D: Cool $unit)
 
+Usage:
+
+    DATETIME.truncated-to(UNIT)
+
 Returns a copy of the invocant, with everything smaller than the specified
 unit truncated to the smallest possible value.
 
@@ -235,32 +350,56 @@ C<.truncated-to('second')>.
 
 =head2 method Date
 
+Defined as:
+
     method Date(DateTime:D:) returns Date:D
 
+Usage:
+
+    DATETIME.Date
+
 Returns a L<Date|/type/Date> object for this DateTime object. Which obviously
 lacks the time component.
 
 =head2 method utc
 
+Defined as:
+
     method utc(DateTime:D:) returns DateTime:D
 
+Usage:
+
+    DATETIME.utc
+
 Returns a DateTime object for the same time, but in time zone UTC.
 
     say DateTime.new('2015-12-24T12:23:00+0200').utc";  # 2015-12-24T10:23:00Z
 
 =head2 method in-timezone
 
+Defined as:
+
     method in-timezone(DateTime:D: $timezone = 0) returns DateTime:D
 
+Usage:
+
+    DATETIME.in-timezone
+
 Returns a DateTime object for the same time, but in the specified time zone.
 
     say DateTime.new('2015-12-24T12:23:00Z').in-timezone(3600 + 1800);
         # 2015-12-24T13:53:00+0130
 
 =head2 method local
 
+Defined as:
+
     method local(DateTime:D:) returns DateTime:D
 
+Usage:
+
+    DATETIME.local
+
 Returns a DateTime object for the same time, but in the local time zone
 (C<$*TZ>).