docs: add Google-style summary lines to docstrings in operations/

[TaiSakuma]

Context

#3946 was a pilot that added a Google-style one-line summary to ak.flatten. The rendering pipeline issues it surfaced have since been fixed (#3947, #3948, #3965, #3966, #3972), so the same treatment can now be rolled out to the rest of src/awkward/operations/.

This issue tracks that rollout. Filing it to give contributors a heads-up and avoid duplicate work.

Scope

123 files remain. Only ak_flatten.py has a summary line today.

Per-file recipe

Important

Checklist comments below refine this recipe and take precedence over it — read the comments before drafting or reviewing a batch. Current checklists (last updated 2026-07-23; add new ones here): summary line, Returns:, Examples:.

The existing docstrings follow a consistent shape:

"""
Args:
    ...

Returns an array with ... <descriptive paragraph> ...
"""

Conversion:

1. Lift the first sentence of the trailing paragraph into the opening """.
2. Keep Args: untouched.
3. Move remaining narrative under Returns: and/or Examples: headers.
4. Review the summary for accuracy — especially edge cases like axis=None (docs: update ak.flatten docstring to Google style #3946 cycled through four drafts before landing on correct wording).

Awkward Arrays are immutable (see ak_copy.py), so active-voice verbs ("Returns…", "Creates…", "Converts…") are safe without caveats.

Contributing to a batch

• Drafts will be generated with Claude Code and reviewed manually, per agreement in the awkward-uproot meeting.
• Do not use closing keywords (closes #N, fixes #N, resolves #N) referencing this issue in batch PRs — that would close the tracking issue before the remaining batches are done. Use Part of #N or Refs #N instead.
• Tick the corresponding checkbox below when each PR merges.

Batches

• Reducers (19): all, any, sum, prod, count, count_nonzero, min, max, argmin, argmax, mean, std, var, moment, corr, covar, ptp, linear_fit, softmax
• Structural (13): ravel, unflatten, zip, unzip, zip_no_broadcast, cartesian, argcartesian, combinations, argcombinations, concatenate, broadcast_arrays, broadcast_fields, pad_none
• Missing-value (8): fill_none, drop_none, is_none, firsts, singletons, mask, nan_to_none, nan_to_num
• Sorting / indexing (5): sort, argsort, run_lengths, local_index, num
• Math / numeric (5): round, real, imag, angle, isclose
• Likes (3): full_like, ones_like, zeros_like
• Field / name / parameter ops (9): with_field, without_field, with_name, with_parameter, without_parameters, with_named_axis, without_named_axis, fields, parameters
• Type / validity / equality (10): almost_equal, array_equal, is_valid, validity_error, is_categorical, is_tuple, categories, enforce_type, values_astype, strings_astype
• from_* array-library converters (8): from_numpy, from_cupy, from_jax, from_torch, from_tensorflow, from_raggedtensor, from_dlpack, from_rdataframe
• from_* file/format converters (11): from_arrow, from_arrow_schema, from_parquet, from_feather, from_json, from_avro_file, from_safetensors, from_iter, from_buffers, from_regular, from_categorical
• to_* array-library converters (11): to_numpy, to_cupy, to_jax, to_torch, to_tensorflow, to_cudf, to_raggedtensor, to_list, to_layout, to_dataframe, to_rdataframe
• to_* file/format converters (13): to_arrow, to_arrow_table, to_parquet, to_parquet_dataset, to_parquet_row_groups, metadata_from_parquet, to_feather, to_json, to_safetensors, to_buffers, to_packed, to_regular, to_backend
• Misc (8): copy, backend, materialize, transform, where, type, merge_option_of_records, merge_union_of_records

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

[TaiSakuma]

Criteria for the one-line summaries, for consistency across batches.

Summary-line checklist

• Single line. Fits on the opening """ line; no wrap.
• Ends with a period.
• Length. Summary + """ prefix must fit the line-length budget (88 via ruff default → summary body ≤ 81 chars).
• Starts with a verb in indicative present tense, third person singular. Matches the pilot (Returns an array…). Normalize imperatives: Increase → Increases, Return → Returns, Compute → Computes.
• Active voice. Arrays are immutable, so Returns…, Creates…, Converts…, Computes… are safe without caveats.
• Accurate across all modes, within the length budget. Covers the full behavior, not just the default, while still fitting ≤ 81 chars. These two constraints interact. (docs: update ak.flatten docstring to Google style #3946 cycled through four drafts on ak.flatten to land on "one or all levels" for both axis=int and axis=None.)
• Plain English, no backticks around parameter names in the summary, unless the arg name genuinely adds meaning (e.g. ```n``` in ak.combinations — the count is the point of the function).
• No #ak.xxx Pydoc-Markdown cross-references in the summary. Keep those for the body.
• No URLs or links in the summary.
• Avoid repeating the function name when a synonym or effect-based phrasing works — case-by-case judgement.
• Distinct from, but consistent with, sibling operations. ak.cartesian vs ak.argcartesian, ak.combinations vs ak.argcombinations: the arg* variant should clearly read as "…returning integer indexes".
• Preserved original text stays verbatim in the Returns: body. Pilot principle: "intentionally minimal, original text preserved as much as possible." Typos in the original stay in the body unless unambiguously fixing them.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com