From ee4ad2727fcfb949e258e0f215a79d56ea41a173 Mon Sep 17 00:00:00 2001
From: Henri Yandell <bayard@apache.org>
Date: Fri, 8 Dec 2006 09:05:52 +0000
Subject: [PATCH] Added javadoc to explain the quandry in how to count
 month/day differences

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@483891 13f79535-47bb-0310-9956-ffa450edef68
---
 .../lang/time/DurationFormatUtils.java        | 22 ++++++++++++++-----
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/src/java/org/apache/commons/lang/time/DurationFormatUtils.java b/src/java/org/apache/commons/lang/time/DurationFormatUtils.java
index 427c1ed56..4e54fd62f 100644
--- a/src/java/org/apache/commons/lang/time/DurationFormatUtils.java
+++ b/src/java/org/apache/commons/lang/time/DurationFormatUtils.java
@@ -249,7 +249,18 @@ public class DurationFormatUtils {
     /**
      * <p>Formats the time gap as a string, using the specified format.
      * Padding the left hand side of numbers with zeroes is optional and 
-     * the timezone may be specified. 
+     * the timezone may be specified. </p>
+     *
+     * <p>When calculating the difference between months/days, it chooses to 
+     * calculate months first. So when working out the number of months and 
+     * days between January 15th and March 10th, it choose 1 month and 
+     * 23 days gained by choosing January->February = 1 month and then 
+     * calculating days forwards, and not the 1 month and 26 days gained by 
+     * choosing March -> February = 1 month and then calculating days 
+     * backwards. </p>
+     *
+     * <p>For more control, the Joda Time library is recommended
+     * (<a href="http://joda-time.sf.net/"). </p>
      * 
      * @param startMillis  the start of the duration
      * @param endMillis  the end of the duration
@@ -304,11 +315,10 @@ public class DurationFormatUtils {
         while (days < 0) {
             end.add(Calendar.MONTH, -1);
             days += end.getActualMaximum(Calendar.DAY_OF_MONTH);
-//days += 31; // TODO: Need tests to show this is bad and the new code is good.
-// HEN: It's a tricky subject. Jan 15th to March 10th. If I count days-first it is 
-// 1 month and 26 days, but if I count month-first then it is 1 month and 23 days.
-// Also it's contextual - if asked for no M in the format then I should probably 
-// be doing no calculating here.
+            // HEN: It's a tricky subject. Jan 15th to March 10th. If I count days-first it is 
+            // 1 month and 26 days, but if I count month-first then it is 1 month and 23 days.
+            // Also it's contextual - if asked for no M in the format then I should probably 
+            // be doing no calculating here.
             months -= 1;
             end.add(Calendar.MONTH, 1);
         }