Skip to content

Fix calculateCPUPercent docstring parameter names and units#1903

Open
anxkhn wants to merge 1 commit into
apple:mainfrom
anxkhn:docs/stats-cpu-percent-doc-params
Open

Fix calculateCPUPercent docstring parameter names and units#1903
anxkhn wants to merge 1 commit into
apple:mainfrom
anxkhn:docs/stats-cpu-percent-doc-params

Conversation

@anxkhn

@anxkhn anxkhn commented Jul 5, 2026

Copy link
Copy Markdown
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [x] Documentation update

## Motivation and Context
The DocC docstring for `calculateCPUPercent` in
`Sources/ContainerCommands/Container/ContainerStats.swift` documented parameters
that no longer exist on the function. The `- Parameters:` block listed
`cpuUsageUsec1`, `cpuUsageUsec2`, and `timeDeltaUsec`, each described as "in
microseconds", but the actual signature is:

```swift
static func calculateCPUPercent(
    cpuUsage1: Duration,
    cpuUsage2: Duration,
    timeInterval: Duration
) -> Double

So all three documented names were stale and the "microseconds" unit contradicted
the Duration parameter types (the body divides Duration by Duration
directly). DocC / Xcode flag - Parameters: entries whose names do not match the
signature, so this produced parameter-name warnings and misleading docs.

This updates the docstring to the real parameter names and describes them as the
durations they are:

  • cpuUsage1 / cpuUsage2: cumulative CPU time from each sample (the call site
    builds these with .microseconds(cpuUsageUsec) from the cumulative usage
    fields).
  • timeInterval: the elapsed wall-clock time between the two samples (the call
    site passes .seconds(2), the sampling interval).

Comment-only change; no behavior change.

Testing

  • Tested locally
  • Added/updated tests
  • Added/updated docs

Doc-only change, so no unit test applies. Verified with the repo's tooling:

  • swift format lint --strict --configuration .swift-format-nolint on the file:
    exit 0.
  • swift format --configuration .swift-format on the file: no diff (already
    canonical).
  • swift build --target ContainerCommands: builds cleanly; the file recompiles.

The docstring listed the parameters as cpuUsageUsec1, cpuUsageUsec2, and
timeDeltaUsec, each described as microseconds, but the function signature
takes cpuUsage1, cpuUsage2, and timeInterval as Duration values. Rename the
documented parameters to match the signature and describe them as durations
so DocC and Xcode no longer warn about mismatched parameter names.
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