Improve quality of Spoon's API documentation (javadoc) #3923
Labels
Comments
This was referenced May 12, 2021
I-Al-Istannen
added a commit
to I-Al-Istannen/spoon
that referenced
this issue
Jul 2, 2021
Before this patch the CI Javadoc regression check would only look at the
amount of violations and fail the build if they increased:
```
JAVADOC QUALITY SCORE (lower is better)
Compare: 2584
Current: 2592
Javadoc quality has deteriorated!
Run the chore/ci-checkstyle-javadoc.sh script locally to find errors
See INRIA#3923 for details
```
This wasn't really helpful when actually finding the errors, as you
would need to run the checkstyle command locally on both branches and
diff the output yourself. This patch adds a small python script that
tries to (somewhat intelligently) perform this diff in the CI and print
a more useful failure message.
The line numbers in the output will not be correct if the exact same
violation message appears multiple times in a single file, but it is
better than having no feedback.
I-Al-Istannen
added a commit
to I-Al-Istannen/spoon
that referenced
this issue
Jul 2, 2021
Before this patch the CI Javadoc regression check would only look at the
amount of violations and fail the build if they increased:
```
JAVADOC QUALITY SCORE (lower is better)
Compare: 2584
Current: 2592
Javadoc quality has deteriorated!
Run the chore/ci-checkstyle-javadoc.sh script locally to find errors
See INRIA#3923 for details
```
This wasn't really helpful when actually finding the errors, as you
would need to run the checkstyle command locally on both branches and
diff the output yourself. This patch adds a small python script that
tries to (somewhat intelligently) perform this diff in the CI and print
a more useful failure message.
The line numbers in the output will not be correct if the exact same
violation message appears multiple times in a single file, but it is
better than having no feedback.
I-Al-Istannen
added a commit
to I-Al-Istannen/spoon
that referenced
this issue
Jul 2, 2021
Before this patch the CI Javadoc regression check would only look at the
amount of violations and fail the build if they increased:
```
JAVADOC QUALITY SCORE (lower is better)
Compare: 2584
Current: 2592
Javadoc quality has deteriorated!
Run the chore/ci-checkstyle-javadoc.sh script locally to find errors
See INRIA#3923 for details
```
This wasn't really helpful when actually finding the errors, as you
would need to run the checkstyle command locally on both branches and
diff the output yourself. This patch adds a small python script that
tries to (somewhat intelligently) perform this diff in the CI and print
a more useful failure message.
The line numbers in the output will not be correct if the exact same
violation message appears multiple times in a single file, but it is
better than having no feedback.
I-Al-Istannen
added a commit
to I-Al-Istannen/spoon
that referenced
this issue
Jul 4, 2021
Before this patch the CI Javadoc regression check would only look at the
amount of violations and fail the build if they increased:
```
JAVADOC QUALITY SCORE (lower is better)
Compare: 2584
Current: 2592
Javadoc quality has deteriorated!
Run the chore/ci-checkstyle-javadoc.sh script locally to find errors
See INRIA#3923 for details
```
This wasn't really helpful when actually finding the errors, as you
would need to run the checkstyle command locally on both branches and
diff the output yourself. This patch adds a small python script that
tries to (somewhat intelligently) perform this diff in the CI and print
a more useful failure message.
The line numbers in the output will not be correct if the exact same
violation message appears multiple times in a single file, but it is
better than having no feedback.
|
@slarse Is this still open to start with contribution? And i'm willing to work on GSoC 2022 Implement Javadoc quality project idea. |
|
Hi @bhargavi-kotha, Yes, this issue is still open and there should be countless Javadoc issues left. You are pretty fast because I have still no confirmation that we are accepted as GSoC project. In the next days(when I/we get the confirmation) we create a new GSoC post on things you can do to get into the project spoon. For now, you can have a look at the old post from @monperrus #3828 from 2021. |
|
What @MartinWitt said :) |
|
Thanks @MartinWitt and @slarse . I would go through any documentation and explore the project. would start off with any issue, until we get confirmation. |
|
Javadoc warnings today |
monperrus
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
A lot of the Javadoc comments int the public API are missing documentation for things like parameters and return types (think
@paramand@returntags). In my opinion, the most glaring omissions of these details are in the metamodel docs, found in the subpackages ofspoon.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.
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:
To get only the errors of a particular file, it's almost always sufficient to use the regex
/ClassName.java. For example, forProcessingManagererrors, you can execute the script like so.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.pywith the--helpflag.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.
The text was updated successfully, but these errors were encountered: