Fix summarize_waterdata_samples doc claims that contradict the service

[thodson-usgs]

Summary

The roxygen doc for summarize_waterdata_samples contains two statements that conflict with the function's own behavior and with the underlying /samples-data/summary/{id} service.

Bug 1: comma-separated identifiers are not supported

Doc states:

Location identifiers should be separated with commas, for example:
AZ014-320821110580701, CAX01-15304600, USGS-040851385.

The function rejects vectors of length > 1:

if (length(monitoringLocationIdentifier) > 1) {
  stop("Summary service only available for one site at a time.")
}

The endpoint is path-based (/summary/{id}), so a comma-joined value would be sent as a single literal path segment, not a list.

Bug 2: bare identifiers are not auto-prefixed with USGS-

Doc states:

Location numbers without an agency prefix are assumed to have the
prefix USGS.

Verified against the live API:

$ curl -s "https://api.waterdata.usgs.gov/samples-data/summary/USGS-04183500?mimeType=text/csv" | head -2
monitoringLocationIdentifier,characteristicGroup,characteristic,characteristicUserSupplied,resultCount,activityCount,firstActivity,mostRecentActivity
USGS-04183500,Information,...,893,893,2017-01-02,2026-04-28
# 110 data rows

$ curl -s "https://api.waterdata.usgs.gov/samples-data/summary/04183500?mimeType=text/csv" | head -2
monitoringLocationIdentifier,characteristicGroup,characteristic,characteristicUserSupplied,resultCount,activities,firstActivity,mostRecentActivity
# 0 data rows; note column "activities" replaces "activityCount"

Bare identifiers return HTTP 200 with zero rows and a different response schema. No client- or server-side prefixing occurs.

Likely origin

Both statements appear to have been carried over from construct_waterdata_sample_request, whose multi-site /results/<profile> endpoint accepts list-valued query parameters. They do not apply to the single-site /summary/{id} endpoint wrapped by this function.

Change

Replace the two statements with single-site guidance and an explicit note that the agency prefix is required.

Test plan

• Doc-only change; no behavioral risk.
• Verified against the live USGS Water Data API on 2026-05-05.
• Reviewer: run devtools::document() to refresh the .Rd file from this roxygen change.

Cross-reference

Identified during equivalent Python work in DOI-USGS/dataretrieval-python#262.