IOUtils clean up javadoc

[wodencafe]

This PR removes some redundant methods from IOUtils, specifically those which use String and StringBuffer, as the same methods that accept CharSequence as a parameter exist, and it is the interface that String and StringBuffer both implement.
There are some other minor code and documentation tweaks.

EDIT: This PR now just updates the javadoc of IOUtils to be more accurate and tidier.

[kinow]

This would need a JIRA issue, and since public methods are being removed, I think we will need to bump it to the next major release (or just deprecate instead of removing methods). Thanks!

[wodencafe]

Hi @kinow , thank you for taking the time to review this pull request. I have a question for you about the deprecated / removed methods. Since CharSequence is the interface that is implemented by the types that the (removed in the PR) methods accepted as first parameter (String, StringBuffer), is it still necessary to retain those overloaded methods, since the existing methods that accept CharSequence are using the same logic?

[kinow]

Hi @kinow , thank you for taking the time to review this pull request. I have a question for you about the deprecated / removed methods. Since CharSequence is the interface that is implemented by the types that the (removed in the PR) methods accepted as first parameter (String, StringBuffer), is it still necessary to retain those overloaded methods, since the existing methods that accept CharSequence are using the same logic?

Hi @wodencafe the issue is backward compatibility.

If we remove public methods (or modify the code in a way that breaks binary backward compatibility ¹² or sometimes behavioral backward compatibility ³⁴) we need to think about the users of the API first.

We could have users of Commons IO that are using those methods in their code. So if we remove these methods, users would expect a major version release so they are aware that there are API changes. Releasing major versions can be inconvenient to users too, as even those that were not affected will have to either review the changes or simply upgrade their code. For that reason, we accumulate changes that require major releases by deprecating unwanted code whenever possible.

I think your change makes sense, if users can rely on the parent type for String/StringBuffer. That would be less code to maintain I guess. We just may need to delay reviewing and merging it until we are ready for a major release 👍

Hope that makes sense.

Thanks!
Bruno

Footnotes

1. https://www.oracle.com/java/technologies/compatibility.html#binary ↩

2. https://en.wikipedia.org/wiki/Binary-code_compatibility ↩

3. https://www.oracle.com/java/technologies/compatibility.html#behavioral ↩

4. https://docs.microsoft.com/en-us/dotnet/core/compatibility/categories#behavioral-change ↩

[garydgregory]

-1 this breaks binary compatibility. There is no need to do that at this time.

We can consider dropping all deprecations in 3.0, and there are no plans for that yet.

[wodencafe]

Ah thank you for providing links and explaining @kinow and @garydgregory , I will put the methods back and update the pull request accordingly.

[kinow]

Brilliant @wodencafe ! I haven't looked at CI, but it appears to be failing. We need to confirm if it is something with this PR or if it is failing on master too.

[garydgregory]

Binary compatibility is still broken. See the builds referred to from this PR.

[garydgregory]

Let's close this PR unless there are changes that won't break BC.

[wodencafe]

Let's close this PR unless there are changes that won't break BC.

Hi @garydgregory and @kinow , I have an updated version of this branch locally that only changes the Javadocs to appropriately match the contract / functionality of the IOUtils methods, and also some misc. formatting / fixes to the existing Javadoc itself. I should be able to push the changes tonight / tomorrow.

Thank you for the review and feedback.

[wodencafe]

Hello again @kinow and @garydgregory , I have updated this Pull Request to tidy up the javadoc in IOUtils.

[garydgregory]

Lots of changes here, TY. I'll try to go through them all this weekend.

[garydgregory]

HI @wodencafe
It's quite hard to review such a giant changeset that claims to only be about Javadoc but also changes the code in contentEqualsIgnoreEOL, so let's drop code changes, then I can just review Javadoc. TY.

[garydgregory]

This is no good IMO: "a a new char array" is clear and correct. "a new {@code char} array" would also be correct as would "a new {@code char[]}" BUT "a "new {@code char[]} array" reads like an array of array. So let's pass on this.

[garydgregory]

Closing, no feedback.