As far as I understand, the maven-javadoc-plugin can be used to check JavaDocs.
I’ve seen that the seata_codeStyle.xml file contains JavaDoc-related settings, and as you mentioned, most of them appear to be set to false, so they’re not actively enforced at the moment. However, what I’d like to discuss in this discussion is a bit different. I’m not referring to JavaDocs that can be validated by a plugin in terms of format or syntax. My main concerns are things like where the Javadoc should be located and which tags should be used, as well as what type of PR should include Javadoc. — something that plugins alone can’t reliably verify. For example, public methods like doBranchDelete and doGlobalRollback in the DefaultCoordinator class currently do not have any JavaDoc. What I’d like to discuss is whether we should require documentation for such "visible" things. On 2025/05/15 07:02:41 Min Ji wrote: > 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 <[email protected]> 于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: [email protected] > > For additional commands, e-mail: [email protected] > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
