docs: copy-edit docstrings and comments for clarity and accuracy

[thodson-usgs]

What

A copy-edit and accuracy review pass over the package's docstrings and inline
comments — spelling, grammar, clarity, and (most importantly) making the prose
match what the code actually does. Docstrings/comments only; no executable
code, signatures, or doctest example code changed.

Notable accuracy fixes (docs that disagreed with the code)

• waterdata/api.get_monitoring_locations — three params documented as
  float are actually string or iterable of strings.
• nwis.query_waterservices — a duplicated ssl_check block; bBox was
  described as a "7-digit HUC" (it's a bounding box).
• waterdata/utils._switch_properties_id — docstring described a dict
  (copy-pasted from _switch_arg_id); the function takes a list[str] | None.
  Also refreshed _get_resp_data / _get_args notes for the now-always-
  materialized id column and numeric-param listifying.
• nwis — getter Returns referenced a nonexistent utils.Metadata;
  corrected to nwis.NWIS_Metadata. Removed a spurious (df, metadata) entry
  from _read_json (it returns a DataFrame).
• RST/numpydoc — "Return"→"Returns", ".. note:"→".. note::".

Additions where docs were silent

• Deprecation note on the nadp module docstring.
• Raises sections on utils.query and streamstats.get_watershed; the
  format param + dual return type on get_watershed.
• Params missing from get_channel's docstring (bbox, last_modified, limit).
• Dropped bogus Returns blocks from __init__ methods (they return None).

Spelling/grammar

"Times series"→"Time series", "datetme"→"datetime", "conatining",
"indeces"→"indices", "ESPSG"→"EPSG", "NDAP"→"NADP", plus a/an and spacing.

Noticed but left for maintainer judgment (out of scope for a copy-edit)

• get_time_series_metadata's properties option list looks copy-pasted from
  get_daily and is likely stale — couldn't verify the correct set.
• get_stats_por / get_stats_date_range have no Returns section.
• A malformed URL in an nwis.get_info runtime warnings.warn(...):
  waterdata.usgs.gov.nwis/qwdata (should be /nwis/) — in executable code, so
  left for a separate fix.
• Older bbox docstrings still use R-style c(xmin, ymin, ...) notation.

Verification

ruff check + ruff format --check clean; package imports clean; docs-only so
no runtime/test impact. Scope: source-code docstrings/comments only (the docs/
RST and notebooks were not part of this pass).

🤖 Generated with Claude Code

---

Update — follow-up commits

Second copy-edit pass caught more misses: 9 Returns cross-references to a
nonexistent utils.Metadata in wqp.py -> wqp.WQP_Metadata;
query_waterdata/query_waterservices examples that listed services the
functions reject; wrong id/empty-frame behavior notes in
_handle_stats_nesting / _combine_chunk_frames; another bogus __init__
Returns; a nadp param-order mismatch; streamstats branding.

Resolved three of the flagged items (incl. two small code fixes):

• Removed the non-functional time parameter from get_monitoring_locations —
  the collection has no time property (verified via its OGC queryables), so
  time=... only ever produced an opaque 400 InvalidQuery. Removal yields a
  clear client-side TypeError instead. Verified against the live API.
• Fixed a malformed URL in the nwis seriesCatalogOutput deprecation
  warning (usgs.gov.nwis/qwdata -> usgs.gov/nwis/qwdata).
• De-R-ified the bbox docstrings (c(xmin,ymin,xmax,ymax) -> [xmin, ymin, xmax, ymax]).

This PR is now mostly docstrings/comments plus those two small, verified code
fixes. ruff clean; 471 tests pass.

Still open for maintainer judgment

• get_time_series_metadata's properties option list looks copy-pasted from
  get_daily and is likely stale (needs the API schema to correct).
• get_stats_por / get_stats_date_range lack Returns sections.
• Sibling site/metadata getters may share the time-param copy-paste; only
  get_monitoring_locations was verified here.