Skip to content

Commit d4370f5

Browse files
authored
Update DOCUMENTATION.md
1 parent 690040a commit d4370f5

File tree

1 file changed

+2
-25
lines changed

1 file changed

+2
-25
lines changed

DOCUMENTATION.md

Lines changed: 2 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -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
191176
Good documentation answers three questions:
@@ -194,11 +179,3 @@ Good documentation answers three questions:
194179
3. **How** do I use it? (example)
195180
196181
Keep 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

Comments
 (0)