Document all public objects with YARD

[tas50]

Description

CONTRIBUTING.md already said documentation was expected, and YARD was already wired up — the rake task, the yard gem, and the .yardoc gitignore entry were all in place. But nothing ever checked, and coverage had drifted:

Before:  61.59% documented   (164 undocumented objects)
After:  100.00% documented   (0 undocumented objects)

The gap was not in obscure corners. Every matcher class, all 15 error classes, both runners, the whole stubs subsystem, and the ChefSpec module itself had no comment at all.

What's here

Documentation — YARD comments for the 164 undocumented objects, following the existing house style (bare # lines opening and closing each block, @param/@return separated by bare # lines). Every changed line under lib/ is a comment: 1267 added, 0 removed, so no behavior can have changed.

.yardopts — so yard doc produces consistent output with the README as the front page. Markup is deliberately left at YARD's rdoc default: the existing docstrings use +template+ rather than backticks, and switching to Markdown would render all of that literally.

tasks/yard_coverage.rb + rake yard:coverage — a local check that reports anything public without a comment, exiting non-zero and naming the offending file:line. It drives YARD's own CLI::Stats rather than reimplementing the rules, so it cannot disagree with yard stats --list-undoc. Worth knowing that those rules are subtler than they look:

• only public objects count — private and protected methods are exempt
• aliases and constructors are skipped
• a docstring made of nothing but an invisible tag still reads as undocumented, so # @api private on its own does not satisfy it (@deprecated, being visible, does)

My first attempt hand-rolled this and reported 63 false failures against yard stats' zero, which is exactly why it now defers to YARD.

This is a local tool only — nothing is wired into CI, and no workflow files are touched by this PR.

CONTRIBUTING.md gains the expectation plus the conventions behind it, including the RDoc-vs-Markdown gotcha and the rule that cross-gem references need +Chef::Resource+ rather than {Chef::Resource}, since YARD cannot link to a class it has not parsed.

Verification

Check	Result
rake yard:coverage	passes, 100.00%
Check fails when a docblock is removed	verified — exits 1 naming the object and its file:line
cookstyle --chefstyle -c .rubocop.yml	111 files, no offenses
ruby -c on all 74 files in lib/ + tasks/	all parse
yard doc warnings	25, identical set to upstream/main — no new warnings
Non-comment changes under lib/	none

The warning comparison caught real problems on the way: my first pass added six Cannot resolve link warnings by writing {Mash} and {Chef::Resource} for classes that live in other gems. Those are now +Mash+ and +Chef::Resource+.

One caveat on what I could not verify: I was unable to run the RSpec suite — bundle install currently fails building the Windows-only win32-api gem via the Chef git source. That is not specific to this branch: upstream/main fails CI on its last four commits including the current tip, and the other open PRs fail identically. Given the diff is comments-only, the risk is minimal, but the suite has genuinely not run against this.

Types of changes

• Documentation

Checklist

• All public classes, modules, constants, attributes, and methods in lib/ are documented
• No behavior changes — lib/ diff is entirely comments
• yard doc produces no new warnings
• No CI changes
• Lint passes