You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@commons.apache.org by "ParanoidUser (via GitHub)" <gi...@apache.org> on 2024/10/31 17:23:47 UTC

[PR] [LANG-1448] StringUtils JavaDoc page wrong for containsOnly and containsNone [commons-lang]

ParanoidUser opened a new pull request, #1308:
URL: https://github.com/apache/commons-lang/pull/1308

   https://issues.apache.org/jira/browse/LANG-1448
   
   Update Javadoc for `StringUtils.containsOnly` and `StringUtils.containsNone` to accurately describe the use of char varargs.


-- 
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: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [LANG-1448] StringUtils Javadoc wrong for containsOnly and containsNone [commons-lang]

Posted by "garydgregory (via GitHub)" <gi...@apache.org>.
garydgregory commented on PR #1308:
URL: https://github.com/apache/commons-lang/pull/1308#issuecomment-3245078355

   Closing, no action in 9 months.


-- 
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: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [LANG-1448] StringUtils Javadoc wrong for containsOnly and containsNone [commons-lang]

Posted by "garydgregory (via GitHub)" <gi...@apache.org>.
garydgregory commented on code in PR #1308:
URL: https://github.com/apache/commons-lang/pull/1308#discussion_r1824971350


##########
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 @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. 
   



-- 
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: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [LANG-1448] StringUtils Javadoc wrong for containsOnly and containsNone [commons-lang]

Posted by "ParanoidUser (via GitHub)" <gi...@apache.org>.
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 Gregory, 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: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [LANG-1448] StringUtils Javadoc wrong for containsOnly and containsNone [commons-lang]

Posted by "ParanoidUser (via GitHub)" <gi...@apache.org>.
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: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [LANG-1448] StringUtils Javadoc wrong for containsOnly and containsNone [commons-lang]

Posted by "garydgregory (via GitHub)" <gi...@apache.org>.
garydgregory closed pull request #1308: [LANG-1448] StringUtils Javadoc wrong for containsOnly and containsNone
URL: https://github.com/apache/commons-lang/pull/1308


-- 
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: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [LANG-1448] StringUtils Javadoc wrong for containsOnly and containsNone [commons-lang]

Posted by "ParanoidUser (via GitHub)" <gi...@apache.org>.
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: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [LANG-1448] StringUtils Javadoc wrong for containsOnly and containsNone [commons-lang]

Posted by "garydgregory (via GitHub)" <gi...@apache.org>.
garydgregory commented on code in PR #1308:
URL: https://github.com/apache/commons-lang/pull/1308#discussion_r1825242226


##########
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:
   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?
   
   



-- 
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: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org