Improve quality of Spoon's API documentation (javadoc)

A lot of the Javadoc comments int the public API are missing documentation for things like parameters and return types (think @param and @return tags). In my opinion, the most glaring omissions of these details are in the metamodel docs, found in the subpackages of spoon.reflect.

For example, at the time of writing this, CtImport is entirely missing tags in its Javadocs.

What we're currently focusing on is improving the documentation of methods, which is arguably the most important documentation. To facilitate this, we have a script to find checkstyle errors in method Javadoc at chore/check-javadoc-regressions.py. You can use this script for two things, as described below.

Note on script compatibility: You must have Python 3.6+ and Maven installed to run the script. It should work fine in most *NIX environments. For Windows, it will only work if the mvn executable is on the system path (i.e. user path won't work). We recommend using WSL if you're on Windows for minimum hassle.

Find methods with poor Javadoc (i.e. stuff you can fix!)

To find methods with poor Javadoc, run the script and provide a regex to match the filepaths you're interested in. It's sufficient to just supply a "sufficiently unique" partial filepath. For example, to find poor Javadoc in the entirety of Spoon core, run the script like so:

Note: Replace python with whatever executable points to a Python 3.6+ interpreter on your machine!

$ python chore/check-javadoc-regressions.py src/main/java
[ERROR] /home/slarse/Documents/github/cdate/spoon-slarse/src/main/java/spoon/IncrementalLauncher.java:256: Expected @return tag. [JavadocMethod]
[ERROR] /home/slarse/Documents/github/cdate/spoon-slarse/src/main/java/spoon/Launcher.java:103:42: Expected @param tag for 'args'. [JavadocMethod]
[ERROR] /home/slarse/Documents/github/cdate/spoon-slarse/src/main/java/spoon/Launcher.java:180:52: Expected @param tag for 'resource'. [JavadocMethod]
[ERROR] /home/slarse/Documents/github/cdate/spoon-slarse/src/main/java/spoon/Launcher.java:604: Expected @return tag. [JavadocMethod]
[ERROR] /home/slarse/Documents/github/cdate/spoon-slarse/src/main/java/spoon/Launcher.java:644: Expected @return tag. [JavadocMethod]
[... OUTPUT TRUNCATED ...]

To get only the errors of a particular file, it's almost always sufficient to use the regex /ClassName.java. For example, for ProcessingManager errors, you can execute the script like so.

$ python chore/check-javadoc-regressions.py /ProcessingManager.java
[ERROR] /home/slarse/Documents/github/cdate/spoon-slarse/src/main/java/spoon/processing/ProcessingManager.java:32:57: Expected @param tag for 'type'. [JavadocMethod]
[ERROR] /home/slarse/Documents/github/cdate/spoon-slarse/src/main/java/spoon/processing/ProcessingManager.java:39: Expected @return tag. [JavadocMethod]
[ERROR] /home/slarse/Documents/github/cdate/spoon-slarse/src/main/java/spoon/processing/ProcessingManager.java:39:43: Expected @param tag for 'p'. [JavadocMethod]
[ERROR] /home/slarse/Documents/github/cdate/spoon-slarse/src/main/java/spoon/processing/ProcessingManager.java:57: Expected @return tag. [JavadocMethod]
[ERROR] /home/slarse/Documents/github/cdate/spoon-slarse/src/main/java/spoon/processing/ProcessingManager.java:68:54: Expected @param tag for 'elements'. [JavadocMethod]
[ERROR] /home/slarse/Documents/github/cdate/spoon-slarse/src/main/java/spoon/processing/ProcessingManager.java:78:32: Expected @param tag for 'element'. [JavadocMethod]

You can then go about fixing checkstyle errors!

Compare the current branch with the master branch

The second mode of the script is to compare overall Javadoc quality with the master branch. This runs in CI and breaks the build if Javadoc quality deteriorates (the amount of errors increase).

This can be nice to run after you're done with your changes to verify that you've actually improved Javadoc quality. So don't run it unless you've committed all changes! For details, see the help section by running check-javadoc-regressions.py with the --help flag.

Scope of a PR fixing checkstyle errors

The scope of a PR fixing checkstyle errors can range from a single method to an entire file. Try not to fix less than a single method, or work in more than a single file. It's much faster and easier to review a commit that only touches Javadoc in a single file, than it is to do so for edits in many files.

Feel free to fix any related Javadoc errors as well (typos, missing Javadoc body, outright errors, etc) in the Javadoc comments you work on.

With that, happy Javadoc fixing! And feel free to ask questions if anything is unclear.