Back to all reviewers

Ensure documentation completeness

bazelbuild/bazel
Based on 4 comments
Other

All code elements should have sufficient documentation to understand their purpose, usage, and context. This includes adding explanatory comments for non-obvious constants, documenting private functions for maintainability, ensuring grammatical accuracy in all documentation, and providing necessary context such as prerequisites or limitations.

Documentation Other

Reviewer Prompt

All code elements should have sufficient documentation to understand their purpose, usage, and context. This includes adding explanatory comments for non-obvious constants, documenting private functions for maintainability, ensuring grammatical accuracy in all documentation, and providing necessary context such as prerequisites or limitations.

Key areas to address:

  • Add comments to constants or variables that aren’t self-explanatory (e.g., DWP = "dwp" // Name of the debug package action)
  • Document private functions with dev-facing comments explaining their purpose
  • Review documentation for grammatical accuracy and clarity
  • Include relevant context like version requirements, prerequisites, or usage limitations

Example of complete documentation:

// Returns the repository name for the current source file.
// Requires C++20 support for __builtin_FILE functionality.
// Use this from within `cc_test` rules.
static std::string CurrentRepository(const std::string& file = __builtin_FILE());

This ensures that future developers can understand and maintain the code without needing to reverse-engineer functionality or guess at requirements.

4
Comments Analyzed
Other
Primary Language
Documentation
Category

Source Discussions