Open slarse opened 3 years ago
bhargavi-kotha
commented
2 years ago @slarse Is this still open to start with contribution? And i'm willing to work on GSoC 2022 Implement Javadoc quality project idea. can u please guide me on how to start with if not this PR to go on. I have experience on java based microservices and spring boot.I have implemented unit test cases with sonar coverage 85% in many of the projects.
MartinWitt
commented
2 years ago 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 https://github.com/INRIA/spoon/issues/3828 from 2021.
slarse
commented
2 years ago What @MartinWitt said :)
bhargavi-kotha
commented
2 years ago Thanks @MartinWitt and @slarse . I would go through any documentation and explore the project. would start off with any issue, until we get confirmation.
monperrus
commented
2 years ago Javadoc warnings today
[WARNING] Javadoc Warnings
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/compiler/Environment.java:579: warning - invalid usage of tag >
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/processing/AbstractParallelProcessor.java:34: warning - Tag @link: reference not found: Executors#newFixedThreadPool()
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/refactoring/Refactoring.java:234: warning - @param argument "input" is not a parameter name.
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/reflect/code/CtTypePattern.java:29: warning - invalid usage of tag >
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/reflect/factory/Factory.java:371: warning - Tag @see: reference not found: CodeFactory#createJavaDocTag()
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/reflect/factory/Factory.java:371: warning - Tag @see: reference not found: CodeFactory#createJavaDocTag()
[WARNING] javadoc: warning - Tag @link: reference not found: #toString()
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/reflect/visitor/PrettyPrinter.java:73: warning - Tag @link: reference not found: #toString()
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/reflect/visitor/PrettyPrinter.java:73: warning - Tag @link: reference not found: #toString()
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/reflect/visitor/PrettyPrinter.java:73: warning - Tag @link: reference not found: #toString()
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/compiler/Environment.java:579: warning - invalid usage of tag >
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/support/template/Parameters.java:221: warning - @param argument "targetType" is not a parameter name.
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/support/util/internal/ElementNameMap.java:28: warning - invalid usage of tag >
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/reflect/visitor/PrettyPrinter.java:73: warning - Tag @link: reference not found: #toString()
[WARNING] /home/martin/martin-no-backup/spoon/spoon-core/src/main/java/spoon/reflect/visitor/PrettyPrinter.java:73: warning - Tag @link: reference not found: #toString()
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.