Skip to content

docs: add summary lines to 5 math/numeric operation docstrings#4133

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

docs: add summary lines to 5 math/numeric operation docstrings#4133
TaiSakuma wants to merge 3 commits into
scikit-hep:mainfrom
TaiSakuma:docs-math-docstrings

Conversation

@TaiSakuma

Copy link
Copy Markdown
Member

Summary

Rolls the pilot from #3946 out to the 5 operations in the Math / numeric batch of #3980:

round, real, imag, angle, isclose.

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.round Rounds each array element to the given number of decimals.
ak.real Returns the real components of the given array elements.
ak.imag Returns the imaginary components of the given array elements.
ak.angle Returns the counterclockwise angle of each complex element in radians or degrees.
ak.isclose Returns a boolean array of element-wise approximate-equality between two arrays.

Notes for reviewers

  • Pre-existing bug surfaced (left verbatim in the body): ak.round's narrative reads "Returns the real components of the given array elements." — a copy-paste from ak_real.py. The implementation rounds (nplike.round(data, decimals)), and the new summary describes that correctly. The wrong body sentence is preserved per the no-rewrite rule; happy to fix it here or in a follow-up if you prefer.
  • ak.isclose and the NumPy-link sentences stay in the bodies (URLs are not allowed in summaries); the summaries describe the effect instead.
  • ak.angle's "in radians or degrees" covers the deg argument.

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

@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 (9268dd2).
⚠️ Report is 14 commits behind head on main.

Additional details and impacted files
Files with missing lines Coverage Δ
src/awkward/operations/ak_angle.py 100.00% <ø> (ø)
src/awkward/operations/ak_imag.py 100.00% <ø> (ø)
src/awkward/operations/ak_isclose.py 96.42% <ø> (ø)
src/awkward/operations/ak_real.py 100.00% <ø> (ø)
src/awkward/operations/ak_round.py 100.00% <ø> (ø)

@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.round An array with each element rounded to the given number of decimals.
ak.real The real components of the given array elements.
ak.imag The imaginary components of the given array elements.
ak.angle The counterclockwise angle from the positive real axis on the complex plane in the range (-pi, pi], with dtype as a float.
ak.isclose An array of booleans, True where a and b are approximately equal within the given tolerances.

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 5 math/numeric operations in `src/awkward/operations/`:
round, real, imag, angle, isclose.

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-math-docstrings branch from ad8f82d to 9268dd2 Compare June 30, 2026 22:40
@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/PR4133

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