Skip to content

docs: tag every documented method's parameters and return - #58

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

docs: tag every documented method's parameters and return#58
tas50 merged 1 commit into
mainfrom
docs/complete-yard-tags

Conversation

@tas50

@tas50 tas50 commented Aug 24, 2026

Copy link
Copy Markdown
Member

yard stats already reported 100% documented, which hid the actual gap: every method had a docstring, but twelve of them documented only what the method does and left the signature untagged.

# Works out the address Test Kitchen should connect to, allocating a
# public address and forwarding the transport's port when asked to.
def hostname_for(state, server_info)

Prose, no @param, no @return. YARD counts that as documented — the metric measures presence, not completeness — so the driver looked fully covered while a reader still had to go read the body to learn that state is mutated and what comes back.

Twelve methods, all of them either private helpers or initialize:

file methods
driver/cloudstack.rb deploy_instance, hostname_for, apply_credentials
cloudstack/client.rb initialize, job_error
cloudstack/credentials.rb initialize
cloudstack/networking.rb initialize, create_port_forward, teardown, tolerating_missing
cloudstack/server_options.rb initialize, truncate_to_budget

The tags say which state keys each method adds, since that is the part worth knowing and the part the prose kept implicit — deploy_instance gains server_id, hostname_for gains ipaddressid and forwardingruleid, create_port_forward gains forwardingruleid. tolerating_missing also gets the @yield and the @raise it re-raises on.

Documentation only. No behaviour changed.

Verification

  • every method taking arguments now carries @param (checked by script: 0 remaining)
  • yard stats — 44 methods, 0 undocumented, 100%
  • rake test — 63 examples, 0 failures
  • cookstyle --chefstyle — 9 files, no offenses

@tas50
tas50 merged commit 62f4ff1 into main Aug 24, 2026
8 checks passed
@tas50
tas50 deleted the docs/complete-yard-tags branch August 24, 2026 01:49
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