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