ParanoidUser commented on code in PR #1308:
URL: https://github.com/apache/commons-lang/pull/1308#discussion_r1825214097
##########
src/main/java/org/apache/commons/lang3/StringUtils.java:
##########
@@ -1191,13 +1191,13 @@ public static boolean containsIgnoreCase(final
CharSequence str, final CharSeque
* An empty CharSequence (length()=0) always returns true.</p>
*
* <pre>
- * StringUtils.containsNone(null, *) = true
- * StringUtils.containsNone(*, null) = true
- * StringUtils.containsNone("", *) = true
- * StringUtils.containsNone("ab", '') = true
- * StringUtils.containsNone("abab", 'xyz') = true
- * StringUtils.containsNone("ab1", 'xyz') = true
- * StringUtils.containsNone("abz", 'xyz') = false
+ * StringUtils.containsNone(null, *) = true
+ * StringUtils.containsNone("", *) = true
+ * StringUtils.containsNone(*, null) = true
+ * StringUtils.containsNone(*, []) = true
+ * StringUtils.containsNone("abc", ['x', 'y']) = true
+ * StringUtils.containsNone("abc", ['1', '.']) = true
Review Comment:
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:
``` java
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:
``` java
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:
``` java
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?
--
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]