bloomberg / bloomberg/ntf-core
Default settings are not documented and options stream operator is unhelpful
- Dominant language
- C++
- Stars
- 99
- Forks
- 33
- PR merge metrics
- No merged PRs in 30d
Description
The documentation does not state what defaults are used by the various options. For example, in ntca_streamsocketoptions.h, there are numerous settings, but the doc doesn't say what each one is if I don't set it explicitly.
It would be nice to have the documentation complete for this (and quite a few other classes that do similar things). That way, I wouldn't have to read the code or write a test case to find out.
I got surprised by this when I noticed that, by default, Nagle is turned off. That's an unusual default, seeing that native default is to have Nagle turned on. Regardless of whether it makes sense to make this the default or not, if the documentation stated what the default is, I wouldn't have to guess.
I tried looking at the default by inserting the default options into a stream. This prints:
```
[ transport = UNDEFINED sourceEndpoint = NULL reuseAddress = false readQueueLowWatermark = NULL readQueueHighWatermark = NULL writeQueueLowWatermark = NULL writeQueueHighWatermark = NULL sendGreedily = NULL receiveGreedily = NULL sendBufferSize = NULL receiveBufferSize = NULL sendBufferLowWatermark = NULL receiveBufferLowWatermark = NULL sendTimeout = NULL receiveTimeout = NULL keepAlive = NULL noDelay = NULL debugFlag = NULL allowBroadcasting = NULL bypassNormalRouting = NULL leaveOutOfBandDataInline = NULL lingerFlag = NULL lingerTimeout = NULL keepHalfOpen = NULL metrics = NULL loadBalancingOptions = [ ] ]
```
This is not useful because I still can't see what settings are actually in effect.
Contributor guide
Research direction
Start with ntca_streamsocketoptions.h and the default-options stream output included in the issue. Trace how each option's default is established, then document those defaults and clarify the stream representation so it reflects useful effective settings; done means readers no longer need to inspect code or write a test to determine defaults.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- documentation, networking
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100