codeAnqiang-ma opened a new pull request, #1772: URL: https://github.com/apache/commons-lang/pull/1772
The Javadoc of `formatPeriod(long, long, String, boolean, TimeZone)` documents the months/days split with a worked example: > ... 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** ... calculating days backwards. The method returns the second value: ```java // 2006-01-15 -> 2006-03-10, GMT formatPeriod(start, end, "M' months 'd' days'", true, gmt); // returns "1 months 26 days"; Javadoc promises "1 month and 23 days" ``` The negative-days loop borrows `start.getActualMaximum(Calendar.DAY_OF_MONTH)`, the length of the month the period starts in — the backwards calculation the Javadoc disclaims. This is not specific to that example: April 30 to June 15, 2023 gives 1 month 15 days, where the forward calculation gives 16. The behavior is intentional: `DurationFormatUtilsTest.testEdgeDurations` asserts `"01 26"` for exactly this date pair. It was also raised as LANG-815 (closed as Not A Problem), where a patch producing the documented forward result made that assertion fail with `01 23` — the two readings are mutually exclusive. So this PR aligns the Javadoc with the implementation rather than changing behavior: it states the borrowing rule, corrects the example, fixes "it choose", and points to `java.time.Period#between` for the forward calculation. Javadoc only, no behavior change. The default `mvn` goal completes successfully: 89,195 tests, 0 failures, plus Checkstyle, SpotBugs, PMD, RAT, japicmp and Javadoc all clean. - [x] Read the [contribution guidelines](CONTRIBUTING.md) for this project. - [x] Read the [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html) if you use Artificial Intelligence (AI). - [x] I used AI to create any part of, or all of, this pull request. Which AI tool was used to create this pull request, and to what extent did it contribute? Cursor (Claude Opus 5) was used to find the discrepancy, run the reproduction and the test suite, and draft the Javadoc wording and this description. All outputs quoted above are from actual local runs. - [x] Run a successful build using the default [Maven](https://maven.apache.org/) goal with `mvn`; that's `mvn` on the command line by itself. - [ ] Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied. This may not always be possible, but it is a best practice. (No behavioral change; the existing `testEdgeDurations` assertion already pins the documented behavior.) - [x] Write a pull request description that is detailed enough to understand what the pull request does, how, and why. - [x] Each commit in the pull request should have a meaningful subject line and body. Note that a maintainer may squash commits during the merge process. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
