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]

Reply via email to