Clarify description of With function #1096
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I found the previous wording confusing, as the use of "prepend" suggests a position of the key-value pairs that was different than what I observed in the output.
What was changed
I reworded a comment that appears in the generated documentation.
Why?
The comment previously said, "With returns Logger instance that prepend every log entry with keyvals. If logger implements WithLogger it is used, otherwise every log call will be intercepted."
I interpret the use of "prepend" to mean that the key-value pairs I supply will appear first in the output. However, I found that they are the last things to appear. After further experimentation, I found that the KV pairs supplied to
With
appear after both the KV pairs in the parent logger and the string that I provided in the log statement, although they do appear before any KV pairs included in a specific log statement.Chad Retz from the SDK team agreed that prepend was not the correct verb to use here, so I have reworded to remove it. As a result, it no longer makes any guarantee about the position of these key-value pairs, but that seemed like an implementation detail, and I find it to be more clear now because I'm no longer misguided about where within the output line I should be looking.
Checklist
Closes N/A
How was this tested:
I ran
go doc --all
in thelog
subdirectory of mysdk-go
clone and verified that the comment appeared as I had intended.Any docs updates needed?
This change updates the only documentation about
log.With
of which I am aware.