[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:
Backports
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.
This is especially important I think because of the _VA_ARGS_.



 Comments   
Comment by Githook User [ 26/Mar/20 ]

Author:

{'name': 'Henrik Edin', 'username': 'henrikedin', 'email': 'henrik.edin@mongodb.com'}

Message: SERVER-46176 Adding documentation of logging macros in logv2/log.h

(cherry picked from commit e832bf1cfbdf1820427387307752038ee84ee2c1)
Branch: v4.4
https://github.com/mongodb/mongo/commit/1b32c4e1baddf357cbfba32dce35c5eb10b4688d

Comment by Githook User [ 24/Mar/20 ]

Author:

{'name': 'Henrik Edin', 'username': 'henrikedin', 'email': 'henrik.edin@mongodb.com'}

Message: SERVER-46176 Adding documentation of logging macros in logv2/log.h
Branch: master
https://github.com/mongodb/mongo/commit/e832bf1cfbdf1820427387307752038ee84ee2c1

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.

Generated at Thu Feb 08 05:10:42 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.