Document Months.between behaviour

Behaviour in this area is long standing and should not be changed
See #325

src/main/java/org/joda/time/Months.java

@@ -128,6 +128,10 @@ public static Months months(int months) {
      * Creates a <code>Months</code> representing the number of whole months
      * between the two specified datetimes. This method corectly handles
      * any daylight savings time changes that may occur during the interval.
+     * <p>
+     * This method calculates by adding months to the start date until the result
+     * is past the end date. As such, a period from the end of a "long" month to
+     * the end of a "short" month is counted as a whole month.
      *
      * @param start  the start instant, must not be null
      * @param end  the end instant, must not be null
@@ -145,6 +149,10 @@ public static Months monthsBetween(ReadableInstant start, ReadableInstant end) {
      * <p>
      * The two partials must contain the same fields, for example you can specify
      * two <code>LocalDate</code> objects.
+     * <p>
+     * This method calculates by adding months to the start date until the result
+     * is past the end date. As such, a period from the end of a "long" month to
+     * the end of a "short" month is counted as a whole month.
      *
      * @param start  the start partial date, must not be null
      * @param end  the end partial date, must not be null

src/test/java/org/joda/time/TestMonths.java

@@ -104,6 +104,21 @@ public void testFactory_monthsBetween_RInstant() {
         assertEquals(6, Months.monthsBetween(start, end2).getMonths());
     }
 
+    public void testFactory_monthsBetween_RInstant_LocalDate_EndMonth() {
+        assertEquals(0, Months.monthsBetween(
+                new DateTime(2006, 1, 31, 0, 0, 0, PARIS), new DateTime(2006, 2, 27, 0, 0, 0, PARIS)).getMonths());
+        assertEquals(1, Months.monthsBetween(
+                new DateTime(2006, 1, 28, 0, 0, 0, PARIS), new DateTime(2006, 2, 28, 0, 0, 0, PARIS)).getMonths());
+        assertEquals(1, Months.monthsBetween(
+                new DateTime(2006, 1, 29, 0, 0, 0, PARIS), new DateTime(2006, 2, 28, 0, 0, 0, PARIS)).getMonths());
+        assertEquals(1, Months.monthsBetween(
+                new DateTime(2006, 1, 30, 0, 0, 0, PARIS), new DateTime(2006, 2, 28, 0, 0, 0, PARIS)).getMonths());
+        assertEquals(1, Months.monthsBetween(
+                new DateTime(2006, 1, 31, 0, 0, 0, PARIS), new DateTime(2006, 2, 28, 0, 0, 0, PARIS)).getMonths());
+        assertEquals(1, Months.monthsBetween(
+                new DateTime(2006, 1, 31, 0, 0, 0, PARIS), new DateTime(2006, 3, 1, 0, 0, 0, PARIS)).getMonths());
+    }
+
     //-------------------------------------------------------------------------
     @SuppressWarnings("deprecation")
     public void testFactory_monthsBetween_RPartial_LocalDate() {
@@ -118,6 +133,15 @@ public void testFactory_monthsBetween_RPartial_LocalDate() {
         assertEquals(6, Months.monthsBetween(start, end2).getMonths());
     }
 
+    public void testFactory_monthsBetween_RPartial_LocalDate_EndMonth() {
+        assertEquals(0, Months.monthsBetween(new LocalDate(2006, 1, 31), new LocalDate(2006, 2, 27)).getMonths());
+        assertEquals(1, Months.monthsBetween(new LocalDate(2006, 1, 28), new LocalDate(2006, 2, 28)).getMonths());
+        assertEquals(1, Months.monthsBetween(new LocalDate(2006, 1, 29), new LocalDate(2006, 2, 28)).getMonths());
+        assertEquals(1, Months.monthsBetween(new LocalDate(2006, 1, 30), new LocalDate(2006, 2, 28)).getMonths());
+        assertEquals(1, Months.monthsBetween(new LocalDate(2006, 1, 31), new LocalDate(2006, 2, 28)).getMonths());
+        assertEquals(1, Months.monthsBetween(new LocalDate(2006, 1, 31), new LocalDate(2006, 3, 1)).getMonths());
+    }
+
     public void testFactory_monthsBetween_RPartial_YearMonth() {
         YearMonth start1 = new YearMonth(2011, 1);
         for (int i = 0; i < 6; i++) {