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]
