Can maven plugins be used to check javadoc and whether the javadoc specification is built into the plugin? Currently, there are quite a few javadoc errors in our CI process, but they are configured to be ignored. javadoc is a schema that helps developers quickly understand code definitions.
Warm regards, Min Ji YongJun Hong <yongj...@apache.org> 于2025年5月15日周四 14:35写道： > > Sorry, I posted the wrong link. 😅 > > IMO, I think it makes sense to write Javadoc for classes, methods, and > fields that are in a "visible" scope, as described in the link below. > SEE --> > https://google.github.io/styleguide/javaguide.html#s7.3-javadoc-where-required > > > On 2025/05/15 06:28:53 Yongjun Hong wrote: > > Hello Seata Community 🙋 > > > > We’ve observed inconsistencies in the quality of Javadoc comments across > > the Seata codebase. > > These inconsistencies can hinder API discoverability and comprehension for > > both users and contributors. (Honestly, I’m the one who struggles the most > > here! 😂) > > To address this, we propose establishing a set of unified guidelines to > > improve the overall quality and consistency of our documentation. > > > > I believe the documentation needs to improve further if we want people > > around the world to use the project. > > > > Background & Motivation > > > > - Some classes and methods are missing Javadoc, or have insufficient > > descriptions > > - Inconsistent use of tags like @since, @author, etc. > > > > Points we should discuss 🗣️ > > > > - Define which classes and methods require mandatory Javadoc comments > > - Specify required and optional tags (e.g., @param, @return, @since, > > @deprecated) > > - Decide whether Javadoc updates should only be required in feature-related > > PRs, or also in non-feature PRs such as optimise, refactor, or test > > > > IMO, I think it makes sense to write Javadoc for classes, methods, and > > fields that are in a "visible" scope, as described in the link below. > > https://google.github.io/styleguide/javaguide.html#s7.3.1-javadoc-exception-self-explanatory > > > > And, I don’t think it’s necessary to use every Javadoc tag in all cases! > > Looking forward to hearing your thoughts on this! 🚀 > > > > Welcome your feedback and suggestions to help improve the Seata project’s > > documentation standards. > > Thank you! > > > > PS. Once the discussion is settled, I plan to create a file that defines > > the Javadoc conventions and add it to the CONTRIBUTING.md. > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@seata.apache.org > For additional commands, e-mail: dev-h...@seata.apache.org > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@seata.apache.org For additional commands, e-mail: dev-h...@seata.apache.org
