docs: add summary lines to 8 misc operation docstrings#4140
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files
|
|
Follow-up per @ikrommyd's review on #4130: the Returns
|
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>
da77efb to
0de45cb
Compare
…. Refs scikit-hep#3980. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The documentation preview is ready to be viewed at http://preview.awkward-array.org.s3-website.us-east-1.amazonaws.com/PR4140 |
ariostas
left a comment
There was a problem hiding this comment.
Looks great. Thank you, @TaiSakuma!
ianna
left a comment
There was a problem hiding this comment.
@TaiSakuma -- I concur with @ariostas -- it looks great! Thanks. Please merge it when you complete your checklist. Thanks
|
For this one I looked carefully at the changes and compared the rendered output to make sure it looks good. But I think it's probably safe to assume that the other PR's will be about the same, so I'll only give them a quick pass. |
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:
""".Returns:andExamples: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
ak.copyak.backendak.materializeak.transformak.wherexoryby a condition, or finds where it is True.ak.typeak.merge_option_of_recordsak.merge_union_of_recordsNotes 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.wherecovers both call modes: three-argument selection and the one-argumentnp.nonzero-style positions. The backticks onx/yare the meaning-bearing-argument exception.ak.merge_option_of_records/ak.merge_union_of_recordsboth produce records of options (verified against the implementations); their bodies are single sentences interleaved with doctests, so each sits under oneReturns:header without anExamples:split.ak.backend's summary avoids the body's "None if…" claim, which is unreachable as documented (the implementation raises instead) — body left verbatim.ak.where's#ak.type.UnionTypecross-reference typo, a missing closing backtick inak.transform'sreturn_valueArgs entry, andak.materialize's datedjax.numpy.ndarraynaming.Test plan
Args:blocks and doctests byte-identical; no original narrative text lost.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