[LANG-1448] StringUtils Javadoc wrong for containsOnly and containsNone

[ParanoidUser]

https://issues.apache.org/jira/browse/LANG-1448

Update Javadoc for StringUtils.containsOnly and StringUtils.containsNone to accurately describe the use of char varargs.

[garydgregory]

Hi @ParanoidUser

Using ['1', '.'] is more confusing IMO instead of 'x', 'y', 'z'. You use * and [text] which won't compile either, which ironically, is what the PR's description complains about!

Are we to assume that '.' is a regular expression or a the actual character dot in ['1', '.'] since it's in between y and z examples?

The reason there are many examples in Javadoc is to avoid using BNF or RegEx. I can see an exception for using * but anything more clever than that is going to be counter productive IMO.

[ParanoidUser]

Hi @garydgregory, thank you for your feedback. While reviewing the StringUtils class, I noticed that non-compilable Javadoc examples are quite common. While we could make these examples compilable, I believe their primary purpose is to demonstrate method behavior clearly and concisely.

Let's look at the StringUtils#containsNone(CharSequence, char...) Javadoc as an example:

StringUtils.containsNone(null, *)           = true  // unexpected token *
StringUtils.containsNone("", *)             = true  // unexpected token *
StringUtils.containsNone(*, null)           = true  // unexpected token * + ambiguous method call with null
StringUtils.containsNone(*, [])             = true  // unexpected tokens * and [] 
StringUtils.containsNone("abc", ['x', 'y']) = true  // array type expected
StringUtils.containsNone("abc", ['y', 'z']) = true  // array type expected
StringUtils.containsNone("abc", ['b', 'z']) = false // array type expected

Here is compilable version:

StringUtils.containsNone(null, "abc");        = true
StringUtils.containsNone("", "abc");          = true
StringUtils.containsNone("", (char[]) null);  = true // not very obvious what this sample trying to show 
StringUtils.containsNone("abc", new char[0]); = true // or StringUtils.containsNone("abc")
StringUtils.containsNone("abc", 'x', 'y');    = true
StringUtils.containsNone("abc", 'y', 'z');    = true
StringUtils.containsNone("abc", 'b', 'z');    = false

Or we can continue using special symbols like * (for any value) and [] (for empty arrays/varargs) in documentation, as they better communicate the method's behavior:

StringUtils.containsNone(null, *)         = true  // second argument doesn't matter, due to null
StringUtils.containsNone("", *)           = true  // second argument doesn't matter, due to empty-string
StringUtils.containsNone(*, null)         = true  // first argument doesn't matter, due to null
StringUtils.containsNone(*, [])           = true  // first argument doesn't matter, due to empty-array
StringUtils.containsNone("abc", 'x', 'y') = true  // valid varargs
StringUtils.containsNone("abc", 'y', 'z') = true  // valid varargs 
StringUtils.containsNone("abc", 'b', 'z') = false // valid varargs

What are your thoughts on which style we should use for the documentation?

[garydgregory]

Hello @ParanoidUser

If I had to pick only one style, I would pick "compilable". In an ideal world, I could imagine Javadoc like:

Does this and that.
<p>
For example:
</p>
<pre>{@code
StringUtils.bla("aaa", "bb") == true;
StringUtils.bla("aaa", "zz") == false;
}
<p>
In general, where `*` means any String:
</p>
<pre>{@code
StringUtils.bla("aaa", *) == true;
StringUtils.bla(*, "zz") == false;
}

WDYT?