[SERVER-46176] macros in logv2/log.h are undocumented Created: 14/Feb/20 Updated: 29/Oct/23 Resolved: 24/Mar/20 |
|
| Status: | Closed |
| Project: | Core Server |
| Component/s: | Internal Code |
| Affects Version/s: | None |
| Fix Version/s: | 4.4.0-rc0, 4.7.0 |
| Type: | Improvement | Priority: | Major - P3 |
| Reporter: | Billy Donahue | Assignee: | Henrik Edin |
| Resolution: | Fixed | Votes: | 0 |
| Labels: | None | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original Estimate: | Not Specified | ||
| Issue Links: |
|
||||
| Backwards Compatibility: | Fully Compatible | ||||
| Backport Requested: |
v4.4
|
||||
| Sprint: | Execution Team 2020-04-06 | ||||
| Participants: | |||||
| Description |
|
Needs comments to explain the macros, and how to choose among them. |
| Comments |
| Comment by Githook User [ 26/Mar/20 ] |
|
Author: {'name': 'Henrik Edin', 'username': 'henrikedin', 'email': 'henrik.edin@mongodb.com'}Message: (cherry picked from commit e832bf1cfbdf1820427387307752038ee84ee2c1) |
| Comment by Githook User [ 24/Mar/20 ] |
|
Author: {'name': 'Henrik Edin', 'username': 'henrikedin', 'email': 'henrik.edin@mongodb.com'}Message: |
| Comment by Billy Donahue [ 18/Feb/20 ] |
|
The decls in the headers should have at least a brief 1-line description of what they do, and maybe a reference back to the relevant section of the README. I don't believe the README should be expected to be exhaustive docs of the C++ level. It doesn't, for example, describe the fields or constructors of the LogOptions class, and it shouldn't have to. It just mentions that you provide a LogOptions when you use a LOGV2_OPTIONS macro. The README is a nice supplement and overview, but it isn't a substitute. I don't look at a README and assume I'm looking at exhaustive technical documentation. I didn't know about the README while I was looking in the header for docs, so clearly it should be referenced in the header docs. |