docs: complete the YARD parameter tags on status_report - #172
Merged
Conversation
status_report was the only method left in the driver whose parameters had no @PARAM tags. Document all four keywords and give the existing @return a description, so the YARD tag coverage is complete alongside the 100% object coverage yard stats already reports. Comments only; no behaviour change. Signed-off-by: Tim Smith <tim@mondoo.com>
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
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.
What
yard statshas reported 100.00% documented for a while, but object coverageonly asks whether an object has a docstring -- it says nothing about whether
the tags inside that docstring are complete. Auditing the registry directly for
missing
@param/@returntags turned up exactly one gap in the whole driver:The one method was
Kitchen::Driver::Hyperv#status_report(
lib/kitchen/driver/hyperv.rb), the private helper that builds the hash#statushands back to Test Kitchen. It has four keyword arguments and had no@paramtags at all, plus a bare@return [Hash]with no description.This PR adds those tags and nothing else. It is comments-only.
What this PR does not do
.yardopts. Both already exist andboth still work:
rake yard,rake yard:serverandrake yard:statsare alllisted by
rake -T, andrake yard:statsstill prints100.00% documented.resize_vhddocumentation. There is a known openquestion there: the code resizes the parent VHD while the log message and the
README both describe it as only affecting the differencing disk. One of the two
is wrong, but settling it needs a real Hyper-V host, so I have deliberately left
that comment alone rather than guessing which side to "correct". It is
unrelated to the method changed here and should be resolved separately.
Verification
yardemits no warnings (in particular no@param tag has unknown parameter namemismatches):Docs coverage unchanged:
Tests, same count before and after (comments-only, as expected):
Lint, clean under both the locally resolved version and the newer one CI picks up:
Merge order
No conflicts expected. #169 and #170 have both landed on
mainalready, and thisbranch is cut from the current
main. The only other open non-release PR is #168(
ci:), which touches workflow files rather thanlib/, so the two areindependent and can merge in either order.