Skip to content

docs: add summary lines to 3 *_like operation docstrings#4131

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

docs: add summary lines to 3 *_like operation docstrings#4131
TaiSakuma wants to merge 3 commits into
scikit-hep:mainfrom
TaiSakuma:docs-likes-docstrings

Conversation

@TaiSakuma

Copy link
Copy Markdown
Member

Summary

Rolls the pilot from #3946 out to the 3 operations in the Likes batch of #3980:

full_like, ones_like, zeros_like.

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.full_like Returns an array with the same structure as the input, filled with a given value.
ak.ones_like Returns an array with the same structure as the input, filled with ones.
ak.zeros_like Returns an array with the same structure as the input, filled with zeros.

Notes for reviewers

  • All three originals began "This is the equivalent of NumPy's np.X_like…", which cannot serve as a verb-first summary; the NumPy-equivalence sentence is preserved verbatim in each body.
  • The three summaries form a tight family differing only in the fill description; full_like's source line sits exactly at the 88-char budget.

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 12, 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 (1a35244).

Additional details and impacted files
Files with missing lines Coverage Δ
src/awkward/operations/ak_full_like.py 98.36% <ø> (ø)
src/awkward/operations/ak_ones_like.py 93.75% <ø> (ø)
src/awkward/operations/ak_zeros_like.py 94.73% <ø> (ø)

@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.full_like An array with the same structure as array, with every value replaced by fill_value.
ak.ones_like An array with the same structure as array, with every value replaced by one.
ak.zeros_like An array with the same structure as array, with every value replaced by zero.

TaiSakuma and others added 3 commits June 30, 2026 18:38
Add a Google-style one-line summary and `Returns:`/`Examples:` section
headers to full_like, ones_like, and zeros_like in
`src/awkward/operations/`.

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-likes-docstrings branch from 5464761 to 1a35244 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/PR4131

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