Skip to content

docs: complete the YARD parameter tags on status_report - #172

Merged
tas50 merged 1 commit into
mainfrom
docs/complete-yard-tags
Aug 30, 2026
Merged

docs: complete the YARD parameter tags on status_report#172
tas50 merged 1 commit into
mainfrom
docs/complete-yard-tags

Conversation

@tas50

@tas50 tas50 commented Aug 30, 2026

Copy link
Copy Markdown
Member

What

yard stats has reported 100.00% documented for a while, but object coverage
only 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 / @return tags turned up exactly one gap in the whole driver:

before: methods=68  missing_@param=1  missing_@return=0
after:  methods=68  missing_@param=0  missing_@return=0

The one method was Kitchen::Driver::Hyperv#status_report
(lib/kitchen/driver/hyperv.rb), the private helper that builds the hash
#status hands back to Test Kitchen. It has four keyword arguments and had no
@param tags 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

  • It does not add YARD rake tasks or a .yardopts. Both already exist and
    both still work: rake yard, rake yard:server and rake yard:stats are all
    listed by rake -T, and rake yard:stats still prints 100.00% documented.
  • It does not touch the resize_vhd documentation. There is a known open
    question 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

yard emits no warnings (in particular no @param tag has unknown parameter name mismatches):

$ bundle exec yard 2>&1 | grep -i warn
(no output)

Docs coverage unchanged:

$ bundle exec rake yard:stats
Files:           3
Modules:         3 (    0 undocumented)
Classes:         1 (    0 undocumented)
Constants:       2 (    0 undocumented)
Attributes:      0 (    0 undocumented)
Methods:        31 (    0 undocumented)
 100.00% documented

Tests, same count before and after (comments-only, as expected):

$ bundle exec rake test
122 examples, 0 failures

Lint, clean under both the locally resolved version and the newer one CI picks up:

$ bundle exec cookstyle --chefstyle      # Cookstyle 8.7.6 / RuboCop 1.86.1
12 files inspected, no offenses detected

$ cookstyle _9.0.0_ --chefstyle          # Cookstyle 9.0.0 / RuboCop 1.90.0
12 files inspected, no offenses detected

Merge order

No conflicts expected. #169 and #170 have both landed on main already, and this
branch is cut from the current main. The only other open non-release PR is #168
(ci:), which touches workflow files rather than lib/, so the two are
independent and can merge in either order.

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>
@tas50
tas50 merged commit 63242fa into main Aug 30, 2026
8 checks passed
@tas50
tas50 deleted the docs/complete-yard-tags branch August 30, 2026 03:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant