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.
