Make examples compile, add new examples, remove 'Usage' sections for Date-related types

Author: Altai-man

doc/Type/Date.pod6

@@ -34,36 +34,32 @@ an object the current day according to the system clock.
 
 Defined as:
 
-    proto method new() {*}
+=begin code :skip-test
+proto method new() {*}
+=end code
     multi method new($year, $month, $day, :&formatter) returns Date:D
     multi method new(:$year!, :$month = 1, :$day = 1)  returns Date:D
     multi method new(Str $date)                        returns Date:D
     multi method new(Instant:D $dt)                    returns Date:D
     multi method new(DateTime:D $dt)                   returns Date:D
 
-Usage:
-
-    $date = Date.new(YEAR, MONTH, DAY, FORMATTER?)
-    $date = Date.new(year => YEAR, month => MONTH?, day => DAY?, FORMATTER?)
-    $date = Date.new(YYYY-MM-DD, FORMATTER?)
-    $date = Date.new(now, FORMATTER?)
-    $date = Date.new(DateTime.now, FORMATTER?)
-
 Creates a new C<Date> object, either from a triple of (year, month, day)
 that can be coerced to integers, or from a string of the form C<YYYY-MM-DD>
 (L<ISO 8601|https://en.wikipedia.org/wiki/ISO_8601>), or from an Instant
 or DateTime object.  Optionally accepts a formatter as a named parameter.
 
+    my $date = Date.new(2042, 1, 1);
+    $date = Date.new(year => 2042, month => 1, day => 1);
+    $date = Date.new("2042-01-01");
+    $date = Date.new(now);
+    $date = Date.new(DateTime.now);
+
 =head2 method new-from-daycount
 
 Defined as:
 
     method new-from-daycount($daycount,:&formatter) returns Date:D
 
-Usage:
-
-    $date = Date.new-from-daycount(DAYCOUNT, FORMATTER?)
-
 Creates a new C<Date> object given C<$daycount> which is the number
 of days from epoch Nov. 17, 1858, i.e. the
 L<Modified Julian Day|https://en.wikipedia.org/wiki/Julian_day>.
@@ -77,10 +73,6 @@ Defined as:
 
     method clone(:$year, :$month, :$day)
 
-Usage:
-
-    DATE.clone(YEAR, MONTH, DAY)
-
 Creates a new C<Date> object based on the invocant, but with the given
 arguments overriding the values from the invocant.
 
@@ -92,23 +84,17 @@ Defined as:
 
     method today(:&formatter) returns Date:D
 
-Usage:
-
-    Date.today
-
 Returns a C<Date> object for the current day.  Optionally accepts a
 formatter named parameter.
 
+    say Date.today;
+
 =head2 method later
 
 Defined as:
 
     method later(Date:D: *%unit)
 
-Usage:
-
-    DATE.later(DELTA)
-
 Returns a C<Date> object based on the current one, but with a date delta
 applied. The date delta can be passed as a named argument where the argument
 name is the unit.
@@ -139,23 +125,18 @@ Defined as:
 
     method earlier(Date:D: *%unit)
 
-Usage:
-
-    DATE.earlier(DELTA)
-
 Returns a C<Date> object based on the current one, but with a date delta
 towards the past applied. See L<#method later> for usage.
 
+    my $d = Date.new('2015-02-27');
+    say $d.earlier(month => 5).earlier(:2days);  # 2014-09-25
+
 =head2 method truncated-to
 
 Defined as:
 
     method truncated-to(Date:D: Cool $unit)
 
-Usage:
-
-    DATE.truncated-to(UNIT)
-
 Returns a C<Date> truncated to the first day of its year, month or week.
 For example
 
@@ -170,10 +151,6 @@ Defined as:
 
     method succ(Date:D:) returns Date:D
 
-Usage:
-
-   DATE.succ
-
 Returns a C<Date> of the following day. "succ" is short for "successor".
 
     say Date.new("2016-02-28").succ;   # 2016-02-29
@@ -184,10 +161,6 @@ Defined as:
 
     method pred(Date:D:) returns Date:D
 
-Usage:
-
-    DATE.pred
-
 Returns a C<Date> of the previous day. "pred" is short for "predecessor".
 
     say Date.new("2016-01-01").pred;   # 2015-12-31
@@ -198,10 +171,6 @@ Defined as:
 
     multi method Str(Date:D:) returns Str:D
 
-Usage:
-
-   DATE.Str
-
 Returns a string representation of the invocant, as specified by the
 L<the formatter|/type/Dateish#method_formatter>. If no formatter was
 specified, an (L<ISO 8601|https://en.wikipedia.org/wiki/ISO_8601>) date
@@ -218,12 +187,10 @@ Defined as:
 
     multi method gist(Date:D:) returns Str:D
 
-Usage:
-
-    DATE.gist
-
 Returns the date in C<YYYY-MM-DD> format (L<ISO 8601|https://en.wikipedia.org/wiki/ISO_8601>)
 
+    say Date.new('2015-12-24').gist;                    # 2015-12-24
+
 =head1 Functions
 
 =head2 sub sleep
@@ -234,24 +201,25 @@ Attempt to sleep for the given number of C<$seconds>.  Returns C<Nil> on
 completion.  Accepts C<Int>, C<Num>, C<Rat>, or C<Duration> types as an
 argument since all of these also do C<Real>.
 
-    sleep 5                # Int
-    sleep 5.2              # Num
-    sleep (5/2)            # Rat
-    sleep (now - now + 5)  # Duration
+=for code :skip-test
+sleep 5;                # Int
+sleep 5.2;              # Num
+sleep (5/2);            # Rat
+sleep (now - now + 5);  # Duration
 
 It is thus possible to sleep for a non-integer amount of time.  For
 instance, the following code shows that C<sleep (5/2)> sleeps for 2.5
 seconds and C<sleep 5.2> sleeps for 5.2 seconds:
 
-    my $before = now
-    sleep (5/2)
-    my $after = now
-    say $after-$before  #=> 2.502411561
+    my $before = now;
+    sleep (5/2);
+    my $after = now;
+    say $after-$before;  # 2.502411561
 
-    my $before = now
-    sleep 5.2
-    my $after = now
-    say $after-$before  #=> 5.20156987
+    $before = now;
+    sleep 5.2;
+    $after = now;
+    say $after-$before;  # 5.20156987
 
 =head2 sub sleep-timer
 
@@ -261,7 +229,7 @@ This function is just like C<sleep>, but returns the amount of time
 remaining to sleep as a C<Duration> (which will be 0 if the call was not
 interrupted).
 
-    say sleep-timer 3.14  #=> 0
+    say sleep-timer 3.14;  # 0
 
 =head2 sub sleep-until
 
@@ -275,30 +243,32 @@ sleep until a time in the past.
 
 To sleep until 10 seconds into the future, one could write something like this:
 
-    say sleep-until now+10     #=> True
+    say sleep-until now+10;   # True
 
 Trying to sleep until a time in the past doesn't work:
 
     my $instant = now - 5;
-    say sleep-until $instant   # => False
+    say sleep-until $instant; # False
 
 However if we put the instant sufficiently far in the future, the sleep
 should run:
 
-    my $instant = now + 30
-    # assuming the two commands are run within 30 seconds of one another...
-    say sleep-until $instant   # => True
+=for code :skip-test
+my $instant = now + 30;
+# assuming the two commands are run within 30 seconds of one another...
+say sleep-until $instant; # True
 
 To specify an exact instant in the future, first create a C<DateTime> at the
 appropriate point in time, and cast to an C<Instant>.
 
-    my $instant = DateTime.new(
-        year => 2020,
-        month => 9,
-        day => 1,
-        hour => 22,
-        minute => 5);
-    say sleep-until $instant.Instant  # => True (eventually...)
+=for code :skip-test
+my $instant = DateTime.new(
+    year => 2020,
+    month => 9,
+    day => 1,
+    hour => 22,
+    minute => 5);
+say sleep-until $instant.Instant; # True (eventually...)
 
 This could be be used as a primitive kind of alarm clock.  For instance, say
 you need to get up at 7am on the 4th of September 2015, but for some reason
@@ -308,17 +278,18 @@ C<DateTime.new> uses UTC by default) as an C<Instant> and pass this to
 C<sleep-until>, after which you can play an mp3 file to wake you up instead
 of your normal alarm clock.  This scenario looks roughly like this:
 
-    # DateTime.new uses UTC by default, so get timezone from current time
-    my $timezone = DateTime.now.timezone;
-    my $instant = DateTime.new(
-        year => 2015,
-        month => 9,
-        day => 4,
-        hour => 7,
-        minute => 0,
-        timezone => $timezone
-    ).Instant;
-    sleep-until $instant;
-    qqx{mplayer wake-me-up.mp3};
+=for code :skip-test
+# DateTime.new uses UTC by default, so get timezone from current time
+my $timezone = DateTime.now.timezone;
+my $instant = DateTime.new(
+    year => 2015,
+    month => 9,
+    day => 4,
+    hour => 7,
+    minute => 0,
+    timezone => $timezone
+).Instant;
+sleep-until $instant;
+qqx{mplayer wake-me-up.mp3};
 
 =end pod