@@ -42,11 +42,11 @@ This guide defines documentation standards for the Entropy Engine project. Our g
4242### Keep These Detailed:
4343- ** Constructors/Destructors** - Resource allocation and cleanup behavior
4444- ** Complex algorithms** - Step-by-step explanation if non-trivial
45- - ** Thread safety** - Mention conversationally : "Can be called from any thread"
45+ - ** Thread safety** - For example : "Can be called from any thread"
4646- ** Code examples** - Always include for non-trivial functionality (worth the space!)
4747
4848### Keep These Brief:
49- - ** Simple getters/setters** - One line is enough
49+ - ** Simple getters/setters** - One line is enough. Perhaps even consider if you need to document these if it's extremely obvious what they do.
5050- ** Internal methods** - Focus on purpose, not implementation
5151- ** Parameter descriptions** - One line unless special behavior
5252- ** Member variables** - One-line inline comments
@@ -171,21 +171,6 @@ private:
171171 mutable std::mutex _ mutex; ///< Protects item modifications
172172```
173173
174- ## Quality Checklist
175-
176- Before submitting code, verify:
177- - [ ] All public methods have @brief, parameters, return, and example
178- - [ ] Complex methods have 2-3 lines of explanation
179- - [ ] Examples compile and demonstrate real usage
180- - [ ] No unverifiable performance claims
181- - [ ] Constructor/destructor behavior is documented
182- - [ ] Thread safety is mentioned where relevant
183- - [ ] Private methods are documented (briefly)
184- - [ ] Member variables have inline comments
185- - [ ] Implementation comments (// style) are preserved
186- - [ ] Code examples are kept intact
187- - [ ] Documentation is 40-50% more concise (not 70-80%)
188-
189174## Remember
190175
191176Good documentation answers three questions:
@@ -194,11 +179,3 @@ Good documentation answers three questions:
1941793. **How** do I use it? (example)
195180
196181Keep it concise. If you can't explain it in 3-5 lines, consider whether the API itself is too complex.
197-
198- ## Key Guidelines for Applying Standards
199-
200- 1. **Only modify documentation blocks** (/** */) - never touch implementation comments (//)
201- 2. **Always preserve code examples** - they're essential for understanding
202- 3. **Aim for balanced reduction** - 40-50% more concise, not extreme minimalism
203- 4. **Keep valuable details** - Constructor/destructor behavior, thread safety, error conditions
204- 5. **Focus on clarity** - Shorter doesn't mean cryptic; maintain usefulness
0 commit comments