Incorporate useful information from notes (take #2)

reference/datetime/dateinterval.xml

@@ -123,6 +123,12 @@
 
   <section xml:id="dateinterval.props">
    &reftitle.properties;
+   <warning>
+    <para>
+     The available properties listed below depend on PHP version, and should
+     be considered as <emphasis>readonly</emphasis>.
+    </para>
+   </warning>
    <variablelist>
     <varlistentry xml:id="dateinterval.props.y">
      <term><varname>y</varname></term>
@@ -198,7 +204,7 @@
        If the DateInterval object was created by
        <methodname>DateTimeImmutable::diff</methodname> or
        <methodname>DateTime::diff</methodname>, then this is the
-       total number of days between the start and end dates. Otherwise,
+       total number of full days between the start and end dates. Otherwise,
        <varname>days</varname> will be &false;.
       </para>
      </listitem>
@@ -250,6 +256,13 @@
          <methodname>DateInterval::createFromDateString</methodname> method.
         </entry>
        </row>
+       <row>
+        <entry>8.2.0</entry>
+        <entry>
+         Only the <literal>y</literal> to <literal>f</literal>,
+         <literal>invert</literal>, and <literal>days</literal> will be visible.
+        </entry>
+       </row>
        <row>
         <entry>7.4.0</entry>
         <entry>

reference/datetime/dateinterval/construct.xml

@@ -158,6 +158,32 @@
 
  <refsect1 role="examples">
   &reftitle.examples;
+  <para>
+   <example>
+    <title>Constructing and using <classname>DateInterval</classname> objects</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Create a specific date
+$someDate = \DateTime::createFromFormat("Y-m-d H:i", "2022-08-25 14:18");
+
+// Create interval
+$interval = new \DateInterval("P7D");
+
+// Add interval
+$someDate->add($interval);
+
+// Convert interval to string
+echo $interval->format("%d");
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="php">
+7
+    </screen>
+   </example>
+  </para>
+
   <para>
    <example>
     <title><classname>DateInterval</classname> example</title>

reference/datetime/dateinterval/createfromdatestring.xml

@@ -13,8 +13,10 @@
    <methodparam><type>string</type><parameter>datetime</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Uses the normal date parsers and sets up a DateInterval from the relative
-   parts of the parsed string.
+   Uses the date/time parsers as used in the
+   <classname>DateTimeImmutable</classname> constructor to create a
+   <classname>DateInterval</classname> from the relative parts of the parsed
+   string.
   </para>
  </refsect1>
 
@@ -32,6 +34,10 @@
        <classname>DateTime</classname>, and <function>strtotime</function>
        will be used to construct the DateInterval.
       </para>
+      <para>
+       To use an ISO-8601 format string like <literal>P7D</literal>, you must
+       use the contructor.
+      </para>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -103,6 +109,27 @@ $i = DateInterval::createFromDateString('3600 seconds');
     </programlisting>
    </example>
   </para>
+  <para>
+   <example>
+    <title>Parsing combinations and negative intervals</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
+echo $i->format('%d %h %i'), "\n";
+
+$i = DateInterval::createFromDateString('1 year - 10 days');
+echo $i->format('%y %d'), "\n";
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="shell">
+449 2 70
+1 -10
+    </screen>
+   </example>
+  </para>
   <para>
    <example>
     <title>Parsing special relative date intervals</title>

reference/datetime/dateinterval/format.xml

@@ -162,6 +162,11 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>7.2.12</entry>
+       <entry>The <literal>F</literal> and <literal>f</literal> format
+        will now always be positive.</entry>
+      </row>
       <row>
        <entry>7.1.0</entry>
        <entry>The <literal>F</literal> and <literal>f</literal> format

reference/datetime/dateperiod.xml

@@ -46,13 +46,24 @@
      <varname linkend="dateperiod.constants.exclude-start-date">DatePeriod::EXCLUDE_START_DATE</varname>
      <initializer>1</initializer>
     </fieldsynopsis>
+    <fieldsynopsis>
+     <modifier>const</modifier>
+     <type>int</type>
+     <varname linkend="dateperiod.constants.include-end-date">DatePeriod::INCLUDE_END_DATE</varname>
+     <initializer>2</initializer>
+    </fieldsynopsis>
 
     <classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
     <fieldsynopsis>
      <modifier>public</modifier>
      <type>int</type>
      <varname linkend="dateperiod.props.recurrences">recurrences</varname>
     </fieldsynopsis>
+    <fieldsynopsis>
+     <modifier>public</modifier>
+     <type>bool</type>
+     <varname linkend="dateperiod.props.include_end_date">include_end_date</varname>
+    </fieldsynopsis>
     <fieldsynopsis>
      <modifier>public</modifier>
      <type>bool</type>
@@ -102,6 +113,13 @@
      </listitem>
     </varlistentry>
 
+    <varlistentry xml:id="dateperiod.constants.include-end-date">
+     <term><constant>DatePeriod::INCLUDE_END_DATE</constant></term>
+     <listitem>
+      <para>Include end date, used in <function>DatePeriod::__construct</function>.</para>
+     </listitem>
+    </varlistentry>
+
    </variablelist>
   </section>
 <!-- }}} -->
@@ -119,6 +137,14 @@
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry xml:id="dateperiod.props.include_end_date">
+     <term><varname>include_end_date</varname></term>
+     <listitem>
+      <para>
+       Whether to include the end date in the set of recurring dates or not.
+      </para>
+     </listitem>
+    </varlistentry>
     <varlistentry xml:id="dateperiod.props.include_start_date">
      <term><varname>include_start_date</varname></term>
      <listitem>
@@ -173,6 +199,13 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>8.2.0</entry>
+       <entry>
+        The <constant>DatePeriod::INCLUDE_END_DATE</constant> constant and
+        <property>include_end_date</property> property have been added.
+       </entry>
+      </row>
       <row>
        <entry>8.0.0</entry>
        <entry>

reference/datetime/dateperiod/construct.xml

@@ -31,6 +31,18 @@
   <para>
    Creates a new DatePeriod object.
   </para>
+  <para>
+   <classname>DatePeriod</classname> objects can be used as an iterator to
+   generate a number of <classname>DateTimeImmutable</classname> or
+   <classname>DateTime</classname> object from a <parameter>start</parameter>
+   date, a <parameter>interval</parameter>, and an <parameter>end</parameter>
+   date or the number of <parameter>recurrences</parameter>.
+  </para>
+  <para>
+   The class of returned objects is equivalent to the
+   <classname>DateTimeImmutable</classname> or <classname>DateTime</classname>
+   ancester class of the <parameter>start</parameter> object.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -41,7 +53,7 @@
      <term><parameter>start</parameter></term>
      <listitem>
       <para>
-       The start date of the period.
+       The start date of the period. Included by default in the result set.
       </para>
      </listitem>
     </varlistentry>
@@ -57,15 +69,17 @@
      <term><parameter>recurrences</parameter></term>
      <listitem>
       <para>
-       The number of recurrences. Must be greater than <literal>0</literal>.
+       The number of recurrences. The number of returned results is
+       one higher than this, as the start date is included in the result set
+       by default. Must be greater than <literal>0</literal>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>end</parameter></term>
      <listitem>
       <para>
-       The end date of the period.
+       The end date of the period. Excluded by default in the result set.
       </para>
      </listitem>
     </varlistentry>
@@ -83,10 +97,19 @@
      <term><parameter>options</parameter></term>
      <listitem>
       <para>
-       Can be set to <constant>DatePeriod::EXCLUDE_START_DATE</constant> to
+       A bit field which can be used to control certain behaviour with start-
+       and end- dates.
+      </para>
+      <para>
+       With <constant>DatePeriod::EXCLUDE_START_DATE</constant> you 
        exclude the start date from the set of recurring dates within the
        period.
       </para>
+      <para>
+       With <constant>DatePeriod::INCLUDE_END_DATE</constant> you 
+       include the end date from the set of recurring dates within the
+       period.
+      </para>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -105,6 +128,12 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>8.2.0</entry>
+       <entry>
+        The <constant>DatePeriod::INCLUDE_END_DATE</constant> constant has been added.
+       </entry>
+      </row>
       <row>
        <entry>7.2.19, 7.3.6, 7.4.0</entry>
        <entry>
@@ -185,6 +214,43 @@ foreach ($period as $date) {
 2012-07-15
 2012-07-22
 2012-07-29
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title>DatePeriod example showing all last Thursdays in a year</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$begin = new DateTime('2021-12-31');
+$end = new DateTime('2022-12-31 23:59:59');
+
+$interval = DateInterval::createFromDateString('last thursday of next month');
+$period = new DatePeriod($begin, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
+
+foreach ($period as $dt) {
+    echo $dt->format('l Y-m-d'), "\n";
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+Thursday 2022-01-27
+Thursday 2022-02-24
+Thursday 2022-03-31
+Thursday 2022-04-28
+Thursday 2022-05-26
+Thursday 2022-06-30
+Thursday 2022-07-28
+Thursday 2022-08-25
+Thursday 2022-09-29
+Thursday 2022-10-27
+Thursday 2022-11-24
+Thursday 2022-12-29
 ]]>
     </screen>
    </example>

reference/datetime/functions/date-create.xml

@@ -42,8 +42,9 @@
  <refsect1 role="seealso">
   &reftitle.seealso;
   <simplelist>
-   <member><methodname>DateTime::__construct</methodname></member>
    <member><methodname>DateTimeImmutable::__construct</methodname></member>
+   <member><methodname>DateTimeImmutable::createFromFormat</methodname></member>
+   <member><methodname>DateTime::__construct</methodname></member>
   </simplelist>
  </refsect1>