THis is (code wise) on purpose, because you can't really overflow "32 days" for example (it could be 1month, 4 days to 1 month, 1 days f.e.)

Aye. And i admit i haven't thought of that - feel free to mark me bogus ;-)

Leap years also come to mind now; as i was fixed on the time issue which i have run into i haven't considered dates at all. 

I'd still vote on documentation clarification there though; and maybe giving your explanation as well.

As a side note - i was experimenting with date manipulation (in order to check whether combination of DateTime::add()/diff() would yield what i need) and have run into another (sort of) ambiguity:

$today = new DateTime();
$tomorrow = $today ->add(new DateInterval('P1D');

$today is $tomorrow (as in same object).

I didn't expect that only by examining documentation. I'd change:

Return Values
Returns the modified DateTime. 

to:

Return Values
Returns the modified self object (DateTime). 

I love the ability to do chain calls and actually like this feature - it's just i haven't expected it from core. No real statistics behind it but i have a feeling that most PHP functions don't return self references. Take SimpleXMLElement::addChild() for example as it's a similar case. It returns added child not "self" containing the added child.

No matter - just wondering off there. 

Point is: please be so kind and consider documentation enhancements (although i admit it's not a very critical case and based mostly on my assumptions on how things will work).

Given that patches speak more then words, for format:

http://svn.php.net/viewvc/phpdoc/en/trunk/reference/datetime/dateinterval/format.xml?view=log


--- format.xml?revision=293203  2010-02-13 13:59:58.925136599 +0100
+++ modified.xml        2010-02-13 14:08:12.238423558 +0100
@@ -162,6 +162,33 @@
     </screen>
    </example>
   </para>
+  <para>
+<![CDATA[
+The DateInterval::format() function doesn't recalculate carry over points in
+time nor in date segments. This is expected behaviour because you can't
+overflow "32 days". It could be anything from 1 month, 4 days to 1 month, 1
+day.
+]]>
+   <example>
+    <title><classname>DateInterval</classname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+$interval = new DateInterval('P32D');
+echo $interval->format('%d days');
+
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="php">
+<![CDATA[
+32 days
+]]>
+    </screen>
+   </example>
+  </para>
  </refsect1>

 </refentry>



And for the add function (sub() should be same i suppose):

http://svn.php.net/viewvc/phpdoc/en/trunk/reference/datetime/datetime/add.xml?view=log

--- add.xml?revision=289096     2010-02-13 14:09:57.735365489 +0100
+++ modified2.xml       2010-02-13 14:10:49.675492799 +0100
@@ -49,7 +49,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns the modified DateTime.
+   Returns the modified self object (DateTime).
   </para>
  </refsect1>



TIA

This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.