Skip to content

docs: add summary lines to 9 field/name/parameter operation docstrings#4134

Open
TaiSakuma wants to merge 3 commits into
scikit-hep:mainfrom
TaiSakuma:docs-field-params-docstrings
Open

docs: add summary lines to 9 field/name/parameter operation docstrings#4134
TaiSakuma wants to merge 3 commits into
scikit-hep:mainfrom
TaiSakuma:docs-field-params-docstrings

Conversation

@TaiSakuma

Copy link
Copy Markdown
Member

Summary

Rolls the pilot from #3946 out to the 9 operations in the Field / name / parameter ops batch of #3980:

with_field, without_field, with_name, with_parameter, without_parameters, with_named_axis, without_named_axis, fields, parameters.

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.with_field Returns an array or record with a new field added, or an existing field replaced.
ak.without_field Returns an array or record with the named field removed.
ak.with_name Returns an array or record with the __record__ parameter set to the given name.
ak.with_parameter Returns an array with the given parameter set on the outermost layout node.
ak.without_parameters Returns an array with all parameters removed from every layout node.
ak.with_named_axis Returns an array with named axes attached.
ak.without_named_axis Returns an array with named axes removed.
ak.fields Returns a list of field names or tuple slot numbers for the outermost record.
ak.parameters Returns the parameters dict of the outermost layout node.

Notes for reviewers

  • Pre-existing bug surfaced (left verbatim in the body): ak.with_named_axis's narrative reads "…with a new name." — a copy-paste from ak_with_name.py. The function attaches named axes; the new summary says so. Happy to fix the body here or in a follow-up if you prefer.
  • ak.with_field's "a new field added, or an existing field replaced" reflects the explicit replace-if-exists branch in _impl.
  • ak.with_name keeps __record__ in backticks — it is the literal parameter key being set (the checklist's meaning-bearing exception).
  • ak.without_parameters ("from every layout node") vs ak.with_parameter ("on the outermost layout node") is a real asymmetry in the implementations, not a mirroring defect.

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 Sonnet 4.6, 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 Sonnet 4.6 noreply@anthropic.com

@codecov

codecov Bot commented Jun 12, 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 (6c4b5c3).
⚠️ Report is 14 commits behind head on main.

Additional details and impacted files
Files with missing lines Coverage Δ
src/awkward/operations/ak_fields.py 100.00% <ø> (ø)
src/awkward/operations/ak_parameters.py 68.96% <ø> (ø)
src/awkward/operations/ak_with_field.py 100.00% <ø> (ø)
src/awkward/operations/ak_with_name.py 100.00% <ø> (ø)
src/awkward/operations/ak_with_named_axis.py 100.00% <ø> (ø)
src/awkward/operations/ak_with_parameter.py 100.00% <ø> (ø)
src/awkward/operations/ak_without_field.py 94.87% <ø> (ø)
src/awkward/operations/ak_without_named_axis.py 86.66% <ø> (ø)
src/awkward/operations/ak_without_parameters.py 100.00% <ø> (ø)

@github-actions github-actions Bot added the type/docs PR title type: docs (set automatically) label Jun 13, 2026
@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.with_field An #ak.Array or #ak.Record (or low-level equivalent, if highlevel=False) with a new field attached.
ak.without_field An #ak.Array or #ak.Record (or low-level equivalent, if highlevel=False) with an existing field removed.
ak.with_name An #ak.Array or #ak.Record (or low-level equivalent, if highlevel=False) with a new name.
ak.with_parameter An array with a parameter set on the outermost node of its #ak.Array.layout.
ak.without_parameters An array without any parameters in its #ak.Array.layout, on nodes of any level of depth.
ak.with_named_axis An #ak.Array or #ak.Record (or low-level equivalent, if highlevel=False) with named axes attached.
ak.without_named_axis An #ak.Array or #ak.Record (or low-level equivalent, if highlevel=False) without named axes.
ak.fields A list of the field names (or tuple slot numbers) of the outermost record of array (many types supported, including all Awkward Arrays and Records).
ak.parameters The parameters dict of the outermost node of array (many types supported, including all Awkward Arrays and Records).

TaiSakuma and others added 3 commits June 30, 2026 18:39
Add a Google-style one-line summary and `Returns:`/`Examples:` section
headers to the 9 field/name/parameter operations in
`src/awkward/operations/`: with_field, without_field, with_name,
with_parameter, without_parameters, with_named_axis, without_named_axis,
fields, parameters.

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 Sonnet 4.6 <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-field-params-docstrings branch from 97d116f to 6c4b5c3 Compare June 30, 2026 22:43
@TaiSakuma TaiSakuma marked this pull request as ready for review June 30, 2026 22:54
@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/PR4134

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