Skip to content

docs: add summary lines to 8 misc operation docstrings#4140

Open
TaiSakuma wants to merge 4 commits into
scikit-hep:mainfrom
TaiSakuma:docs-misc-docstrings
Open

docs: add summary lines to 8 misc operation docstrings#4140
TaiSakuma wants to merge 4 commits into
scikit-hep:mainfrom
TaiSakuma:docs-misc-docstrings

Conversation

@TaiSakuma

Copy link
Copy Markdown
Member

Summary

Rolls the pilot from #3946 out to the 8 operations in the Misc batch of #3980 — the last of the 13 batches:

copy, backend, materialize, transform, where, type, merge_option_of_records, merge_union_of_records.

Each docstring now has:

  • A one-line summary on the opening """.
  • Returns: and Examples: section headers (the latter only where examples exist).

Original body text is preserved; only structural edits are applied. The summary lines were reviewed against the checklist posted in #3980.

Summary lines

Operation Summary
ak.copy Returns a deep copy of the array (no memory shared with original).
ak.backend Returns the name of the backend used by the given arrays.
ak.materialize Materializes any virtual buffers in the array.
ak.transform Applies a transformation function to every node of one or more arrays.
ak.where Selects elements from x or y by a condition, or finds where it is True.
ak.type Returns the high-level type of an array as a Type object.
ak.merge_option_of_records Simplifies options of records into records of options.
ak.merge_union_of_records Simplifies unions of records into records of options.

Notes for reviewers

  • ak.transform's summary is deliberately mode-neutral ("Applies a transformation function to every node of one or more arrays.") — accurate for the copy-returning, side-effect (return_value="none"), and multi-array broadcasting modes. Its pre-existing RST-underlined sections (Signature, Contexts, Continuation, Broadcasting, …) are kept byte-identical after the new Google-style sections.
  • ak.where covers both call modes: three-argument selection and the one-argument np.nonzero-style positions. The backticks on x/y are the meaning-bearing-argument exception.
  • ak.merge_option_of_records / ak.merge_union_of_records both produce records of options (verified against the implementations); their bodies are single sentences interleaved with doctests, so each sits under one Returns: header without an Examples: split.
  • ak.backend's summary avoids the body's "None if…" claim, which is unreachable as documented (the implementation raises instead) — body left verbatim.
  • Pre-existing quirks left verbatim: ak.where's #ak.type.UnionType cross-reference typo, a missing closing backtick in ak.transform's return_value Args entry, and ak.materialize's dated jax.numpy.ndarray naming.

Test plan

  • pre-commit passes locally on the modified files (ruff check, ruff format, codespell, mypy).
  • Mechanical validation: code outside docstrings byte-identical; Args: blocks and doctests byte-identical; no original narrative text lost.
  • Sphinx docs build cleanly on CI.
  • Rendered docstrings spot-checked in the docs preview.

Part of #3980. Draft for initial review; will mark ready once CI passes and the preview is checked.

AI assistance disclosure

Drafted with Claude Code: summaries drafted by Claude Fable 5, adversarially verified against the implementations by independent Claude Opus 4.8 agents, mechanically validated (docstring-only changes, original text preserved), and reviewed by a human before submission.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

@github-actions github-actions Bot added the type/docs PR title type: docs (set automatically) label Jun 13, 2026
@codecov

codecov Bot commented Jun 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.74%. Comparing base (722a1b9) to head (6a63577).
⚠️ Report is 13 commits behind head on main.

Additional details and impacted files
Files with missing lines Coverage Δ
src/awkward/operations/ak_backend.py 100.00% <ø> (ø)
src/awkward/operations/ak_copy.py 100.00% <ø> (ø)
src/awkward/operations/ak_materialize.py 93.75% <ø> (ø)
...c/awkward/operations/ak_merge_option_of_records.py 91.42% <ø> (ø)
...rc/awkward/operations/ak_merge_union_of_records.py 82.11% <ø> (ø)
src/awkward/operations/ak_transform.py 96.20% <ø> (ø)
src/awkward/operations/ak_type.py 87.23% <ø> (ø)
src/awkward/operations/ak_where.py 95.65% <ø> (ø)

@TaiSakuma

Copy link
Copy Markdown
Member Author

Follow-up per @ikrommyd's review on #4130: the Returns: sections now describe the returned object (a noun phrase) rather than restating the operation. Final Returns: lines for this batch:

Returns

Operation Returns
ak.copy A deep copy of the array (no memory shared with original).
ak.backend The name of the backend used by arrays.
ak.materialize An array with the same data as the input and all virtual buffers materialized.
ak.transform The array (or arrays) obtained by applying transformation to every node — either a transformed copy, or data extracted from a walk over the arrays' low-level layout nodes.
ak.where An array with elements taken from x where condition is true and from y otherwise (three-argument form), or the integer indices where condition is true (one-argument form).
ak.type The high-level type of an array (many types supported, including all Awkward Arrays and Records) as #ak.types.Type objects.
ak.merge_option_of_records An equivalent array with the option pushed inside the record (a record of options)
ak.merge_union_of_records An equivalent array with the union of records merged into a single record of options

TaiSakuma and others added 3 commits June 30, 2026 18:38
Add a Google-style one-line summary and `Returns:`/`Examples:` section
headers to the 8 remaining operations in `src/awkward/operations/`:
copy, backend, materialize, transform, where, type,
merge_option_of_records, merge_union_of_records.

Follows the pilot in scikit-hep#3946 on `ak.flatten`. Original body text is
preserved; only structural edits are applied.

Refs scikit-hep#3980.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
…#3980.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…tion. Refs scikit-hep#3980.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@TaiSakuma TaiSakuma force-pushed the docs-misc-docstrings branch from da77efb to 0de45cb Compare June 30, 2026 22:46
@TaiSakuma TaiSakuma marked this pull request as ready for review June 30, 2026 22:54
…. Refs scikit-hep#3980.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@github-actions

github-actions Bot commented Jul 1, 2026

Copy link
Copy Markdown

The documentation preview is ready to be viewed at http://preview.awkward-array.org.s3-website.us-east-1.amazonaws.com/PR4140

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type/docs PR title type: docs (set automatically)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant