Improve JavaDocs

[arturobernalg]

Jus add a bunch of javadoc improvement in order to make it more readable when the user search information.

[arturobernalg]

BTW sorry the size of the PR. But IMO it was necessary

[codecov-commenter]

Codecov Report

Merging #956 (0798b65) into master (9a52b9c) will not change coverage. The diff coverage is n/a.

:exclamation: Current head 0798b65 differs from pull request most recent head 2a50d55. Consider uploading reports for the commit 2a50d55 to get more accurate results

@@            Coverage Diff            @@
##             master     #956   +/-   ##
=========================================
  Coverage     91.99%   91.99%           
  Complexity     7432     7432           
=========================================
  Files           189      189           
  Lines         15668    15668           
  Branches       2913     2913           
=========================================
  Hits          14414    14414           
  Misses          677      677           
  Partials        577      577           

Impacted Files	Coverage Δ
...main/java/org/apache/commons/lang3/ArrayUtils.java	95.71% <ø> (ø)
...c/main/java/org/apache/commons/lang3/BitField.java	100.00% <ø> (ø)
...in/java/org/apache/commons/lang3/BooleanUtils.java	94.94% <ø> (ø)
.../main/java/org/apache/commons/lang3/CharRange.java	95.94% <ø> (ø)
...va/org/apache/commons/lang3/CharSequenceUtils.java	91.12% <ø> (ø)
...rc/main/java/org/apache/commons/lang3/CharSet.java	96.36% <ø> (ø)
...in/java/org/apache/commons/lang3/CharSetUtils.java	98.21% <ø> (ø)
.../main/java/org/apache/commons/lang3/CharUtils.java	100.00% <ø> (ø)
...c/main/java/org/apache/commons/lang3/Charsets.java	75.00% <ø> (ø)
...ava/org/apache/commons/lang3/ClassLoaderUtils.java	40.00% <ø> (ø)
... and 74 more

:mega: We’re building smart automated test selection to slash your CI/CD build times. Learn more

[garydgregory]

You really need to build the project locally before you create the PR, see the Javadoc errors.

Aside from that, I'm starting to think that this is really making the code harder to read and that it would be better handled by a Doclet.

[arturobernalg]

HI @garydgregory

You really need to build the project locally before you create the PR, see the Javadoc errors.

Aside from that, I'm starting to think that this is really making the code harder to read and that it would be better handled by a Doclet.

I lose track of what apache jenkings does. I do not have access

[INFO] Configuration changed, re-generating javadoc. [WARNING] Javadoc Warnings [WARNING] warning: URL https://docs.oracle.com/javase/8/docs/api/element-list was redirected to https://docs.oracle.com/en/java/javase/19/ -- Update the command-line options to suppress this warning. [WARNING] 1 warning [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 03:28 min [INFO] Finished at: 2022-09-24T21:01:26+02:00 [INFO] ------------------------------------------------------------------------ abernal@Arturo-MacBook-Pro  ~/IdeaProyect/commons-lang   feature/better_javadoc 

You really need to build the project locally before you create the PR, see the Javadoc errors.

None.

Aside from that, I'm starting to think that this is really making the code harder to read and that it would be better handled by a Doclet.

[garydgregory]

I'm not sure what Jenkins has to do with this. In any case, you can see the failure here:

https://github.com/apache/commons-lang/actions/runs/3119069043/jobs/5058792919

Error:  Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.4.1:javadoc (create-javadoc-jar) on project commons-lang3: An error has occurred in Javadoc report generation: 
Error:  Exit code: 1 - /home/runner/work/commons-lang/commons-lang/src/main/java/org/apache/commons/lang3/reflect/TypeUtils.java:406: error: type arguments not allowed here
Error:       * determine that based on the super type {@link  Iterable<? extends
Error:                                                        ^
Error:  /home/runner/work/commons-lang/commons-lang/src/main/java/org/apache/commons/lang3/reflect/TypeUtils.java:419: warning - Tag @link:illegal character: "60" in "Iterable<? extends
Error:   Map<Integer, ? extends Collection<?>>>"
Error:  /home/runner/work/commons-lang/commons-lang/src/main/java/org/apache/commons/lang3/reflect/TypeUtils.java:419: warning - Tag @link:illegal character: "63" in "Iterable<? extends
Error:   Map<Integer, ? extends Collection<?>>>"
Error:  
Error:  Command line was: /usr/lib/jvm/temurin-8-jdk-amd64/jre/../bin/javadoc @options @packages
Error:  
Error:  Refer to the generated Javadoc files in '/home/runner/work/commons-lang/commons-lang/target/site/apidocs' dir.
Error:  
Error:  -> [Help 1]
Error:  
Error:  To see the full stack trace of the errors, re-run Maven with the -e switch.
Error:  Re-run Maven using the -X switch to enable full debug logging.
Error:  
Error:  For more information about the errors and possible solutions, please read the following articles:
Error:  [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException
Error: Process completed with exit code 1.

[aherbert]

FYI: This javadoc warning:

[WARNING] Javadoc Warnings
[WARNING] warning: URL https://docs.oracle.com/javase/8/docs/api/element-list was
redirected to https://docs.oracle.com/en/java/javase/19/
 -- Update the command-line options to suppress this warning.

Is due to the <links> added to the maven-javadoc-plugin in commons-parent for JDK classes. This seems to not be required when building on recent JDK LTS versions (tested on 8, 11, and 17). Only JDK 17 puts out this warning as it attempts to look up an element-list and not a package-list for the javadoc at the provided URL.

Note: To test locally you simply run maven with the default goal: mvn. Most of the commons GH actions builds are configured to use the default goal.

[arturobernalg]

So do I have to change something? should I close the pr?

[garydgregory]

97 files changed... I should be able to take a look over the weekend.