module params: cleanup warnings - #642
Merged
Merged
Conversation
The per-version line of the coverage report reused the word
"undocumented" for parameters that are described upstream perfectly
well and only lack the curated advice this page exists to add. A
reader who takes it at its word goes looking for l2arc_dwpd_limit,
finds it in the man page with its type, default and description, and
is left wondering what the warning was about.
Documented nowhere is a different bucket: it is reported as an error,
and it is the only one that fails the check. Keep the two apart in
the wording, as the summary line above ("have no curated notes") and
the markdown report ("Missing tuning notes") already do.
The scan for identifiers the curated text names but the sources no longer have reported eleven. Two were real: arcstats has no arc_dnode_size field and never has had one; the field is called dnode_size. Both dnode limit entries told the reader to compare it against arc_dnode_limit, which is real, so the sentence looked right enough to survive. zfs_multihost_import_intervals spelled its own name in the singular inside the literal and hung the plural s outside it with an escape. The formula therefore named a parameter that does not exist, and the trick was invisible in the rendered page. The other nine were the scan's own doing, in three ways. Four entries describe parameters upstream removed in 2.2 and 0.8, and one the vdev cache that is gone entirely; their notes name the rest of that removed world, as they should. check_removed_references() already leaves such entries alone, so leave them alone here too. The grep looked only at *.c and *.h, so all_system_memory and zfs_mg_alloc_failures read as removed although man/man4/zfs.4 in master names both -- the first as the term for installed memory, the second in the same historical aside this page makes. Search the man pages as well. discard_max_bytes and discard_max_hw_bytes belong to the Linux block layer and will never appear in this tree. Name them, with the reason. The other exemption in check_removed_references(), for text that already speaks in the past tense, is deliberately not adopted: applied to a whole entry it exempts 73 of the 282, because ordinary prose says "before" and "prior" all the time, and none of the eleven needs it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
No description provided.