docs: describe the returned object in Returns: for already-merged operations

[TaiSakuma]

Summary

Follow-up to #3980. The structural batch (#3986) added one-line summaries to those 13 operations, but 8 of them kept a Returns: section that restates the operation instead of describing the returned object. @ikrommyd flagged this pattern while reviewing the open batch PRs (e.g. #4130), noting that a few already-merged cases need the same fix. This PR applies the object-style convention to those 8.

Only the first sentence of each Returns: is reworded; the explanatory text below it is unchanged.

Returns

Operation	Returns
ak.zip	An array of records (or tuples) whose fields (or slots) are the arrays, combined into a single structure.
ak.unzip	A Python tuple (or dict) of arrays, one for each field of the tuples or records in array.
ak.zip_no_broadcast	An array of records (or tuples) whose fields (or slots) are the arrays, combined into a single structure.
ak.cartesian	An array holding the Cartesian product (i.e. cross product) of data from a set of arrays.
ak.argcartesian	An array of integer indexes into the Cartesian product of a set of arrays, like ak.cartesian but for use with __getitem__.
ak.combinations	An array holding the Cartesian product of array with itself, restricted to combinations sampled without replacement.
ak.argcombinations	An array of integer indexes into the combinations of array with itself, like ak.combinations but for use with __getitem__.
ak.pad_none	An array whose lists are padded with None to at least the target length.

Notes for reviewers

• Pure docstring change; no code touched. ruff check, ruff format, and codespell pass on the modified files.
• Refs #3980 — no closing keyword, so the tracking issue stays open.

AI disclosure

Drafted with Claude Code (Claude Opus 4.8) and reviewed manually, per the contribution agreement in #3980.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.74%. Comparing base (722a1b9) to head (f28bb49).

Additional details and impacted files

Files with missing lines	Coverage Δ
src/awkward/operations/ak_argcartesian.py	83.33% <ø> (ø)
src/awkward/operations/ak_argcombinations.py	92.30% <ø> (ø)
src/awkward/operations/ak_cartesian.py	92.24% <ø> (ø)
src/awkward/operations/ak_combinations.py	88.46% <ø> (ø)
src/awkward/operations/ak_pad_none.py	100.00% <ø> (ø)
src/awkward/operations/ak_unzip.py	90.00% <ø> (ø)
src/awkward/operations/ak_zip.py	96.07% <ø> (ø)
src/awkward/operations/ak_zip_no_broadcast.py	86.44% <ø> (ø)

[ianna]

@TaiSakuma - Looks great! Thanks for fixing it. It's good to get merged if you are done with it.

[ikrommyd]

The comments from #4130 are valid for this one too. I think that we had for "returns" here should just be moved right below it as normal text/description of the function right and the returns statement should be a sentence in the fashion of the "Args" descriptions right above.

[TaiSakuma]

@ikrommyd - I think that I understand what you have been saying. I just realized that the table in the PR description and the equivalent tables in the other PRs are wrong. The Returns fields in the commits actually have much longer contents. We can see how it looks on the doc if #4155 fixes the preview. I agree that some Returns fields have too much content. But I don't think the extra text should be moved right below it as normal text/description, because that is not the best place for a text/description without a heading. They can go above Args.

[TaiSakuma]

Here's the corrected table showing the full Returns content currently in the commits — the table in the PR description lists only the first sentence of each. <br><br> marks paragraph breaks.

Operation	Returns (full content)
ak.zip	An array of records (or tuples) whose fields (or slots) are the arrays, combined into a single structure. If the arrays have nested structure, they are broadcasted with one another to form the records or tuples as deeply as possible, though this can be limited by depth_limit. This operation may be thought of as the opposite of projection in #ak.Array.__getitem__, which extracts fields one at a time, or #ak.unzip, which extracts them all in one call.
ak.unzip	A Python tuple (or dict) of arrays, one for each field of the tuples or records in array. If the array does not contain tuples or records, the single array is placed in a length 1 Python tuple (or dict).
ak.zip_no_broadcast	An array of records (or tuples) whose fields (or slots) are the arrays, combined into a single structure. Caution: unlike #ak.zip this function will not broadcast the arrays together. During typetracing, it assumes that the given arrays have already the same layouts and lengths. This operation may be thought of as the opposite of projection in #ak.Array.__getitem__, which extracts fields one at a time, or #ak.unzip, which extracts them all in one call.
ak.cartesian	An array holding the Cartesian product (i.e. cross product) of data from a set of arrays. This operation creates records (if arrays is a dict) or tuples (if arrays is another kind of iterable) that hold the combinations of elements, and it can introduce new levels of nesting.
ak.argcartesian	An array of integer indexes into the Cartesian product (i.e. cross product) of a set of arrays, like #ak.cartesian but for use with #ak.Array.__getitem__.
ak.combinations	An array holding the Cartesian product (i.e. cross product) of array with itself, restricted to combinations sampled without replacement. If the normal Cartesian product is thought of as an n dimensional tensor, these represent the "upper triangle" of sets without repetition. If replacement=True, the diagonal of this "upper triangle" is included.
ak.argcombinations	An array of integer indexes into the combinations of array with itself (sampled without replacement), like #ak.combinations but for use with #ak.Array.__getitem__. The motivation and uses of this function are similar to those of #ak.argcartesian. See #ak.combinations and #ak.argcartesian for a more complete description.
ak.pad_none	An array whose lists are padded with None to at least the target length.

ak.argcartesian and ak.pad_none are already a single noun clause; the rest carry the extra prose shown above.

🤖 Generated with Claude Code

[TaiSakuma]

Posted by Claude Code.

Proposed Returns: convention for the #3980 docstring batch

This spec is precise enough to apply mechanically across this PR and the sibling batch PRs (#4130 etc.).

Rule

1. Returns: holds exactly one short noun clause naming the returned object and its type sense — e.g. "An array of …", "A Python tuple (or dict) of arrays, …". It must describe the object returned, never restate the operation ("Computes…", "Combines…", "Increase the lengths…").
2. Everything else currently inside the Returns: block (extra sentences, paragraphs, caveats, cross-references to related ops) moves to the extended description — the paragraph(s) directly below the summary line and above Args:.

How to apply (mechanical)

1. Find the docstring summary line (first line after the opening """).
2. Find the Returns: block: from Returns: to the next section header (Examples:, See Also:, …) or the closing """.
3. Reduce Returns: to just its leading noun clause.
   • If that leading sentence currently restates the operation, reword only it into an object-describing noun clause. Keep the same facts; do not invent new ones.
4. Move the removed sentences/paragraphs into the extended description:
   • Insert one blank line after the summary line, then the moved paragraphs, then a blank line before Args:.
   • If an extended description already exists, append the moved paragraphs after it (preserve existing order; do not duplicate).
5. Re-indent moved text from the Returns: body indent (8 spaces) to the docstring body indent (4 spaces) and re-wrap to the file's existing line width. Otherwise move it verbatim — no rewording of relocated prose; preserve #ak.* cross-references exactly.
6. Do not touch Args:, Examples:, code, or the signature.

Worked example — ak.zip

Before:

    """Combines arrays into records or tuples, broadcasting them together.

    Args:
        arrays (mapping or sequence of arrays): Each value in this mapping or
            sequence can be any array-like data that #ak.to_layout recognizes.
        ...  # other args unchanged
        attrs (None or dict): Custom attributes for the output array, if
            high-level.

    Returns:
        An array of records (or tuples) whose fields (or slots) are the `arrays`,
        combined into a single structure. If the `arrays` have
        nested structure, they are broadcasted with one another to form the
        records or tuples as deeply as possible, though this can be limited by
        `depth_limit`.

        This operation may be thought of as the opposite of projection in
        #ak.Array.__getitem__, which extracts fields one at a time, or
        #ak.unzip, which extracts them all in one call.

    Examples:
        ...
    """

After:

    """Combines arrays into records or tuples, broadcasting them together.

    If the `arrays` have nested structure, they are broadcasted with one
    another to form the records or tuples as deeply as possible, though this
    can be limited by `depth_limit`.

    This operation may be thought of as the opposite of projection in
    #ak.Array.__getitem__, which extracts fields one at a time, or #ak.unzip,
    which extracts them all in one call.

    Args:
        arrays (mapping or sequence of arrays): Each value in this mapping or
            sequence can be any array-like data that #ak.to_layout recognizes.
        ...  # other args unchanged
        attrs (None or dict): Custom attributes for the output array, if
            high-level.

    Returns:
        An array of records (or tuples) whose fields (or slots) are the
        `arrays`, combined into a single structure.

    Examples:
        ...
    """

Scope

Apply to every operation whose Returns: either (a) restates the operation in its first sentence, or (b) carries more than a single noun clause.

• This PR: ak.zip, ak.unzip, ak.zip_no_broadcast, ak.cartesian, ak.combinations, ak.argcombinations. (ak.argcartesian and ak.pad_none already comply.)
• Sibling PRs (docs: add summary lines to 8 missing-value operation docstrings #4130 etc.): same transform — note many of those still need step 3's reword (e.g. Returns:\n Removes missing values (None)… → An array with missing values (None) removed).

After editing

ruff format, ruff check, and codespell should pass on the modified files — this is a pure docstring change with no functional effect.

🤖 Generated with Claude Code

[TaiSakuma]

@ikrommyd - The proposed change in the above comment has been implemented.

[github-actions]

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

[ikrommyd]

Good! One final style thing. Do you think it's best to have the longer description above the parameters like we do now (http://preview.awkward-array.org.s3-website.us-east-1.amazonaws.com/PR4148/reference/generated/ak.zip.html) or have it below the returns and above the examples?

[TaiSakuma]

Yes. I think the space above the first heading ("Parameters") is the best place for a description that doesn't belong to any specific heading. I think that it is quite uncommon to have text without a heading between the Returns and Examples sections. If we want the text there, that should be part of the Returns section.

[ikrommyd]

Well I think we already have text in multiple places that is between the returns statement and the examples. Anything below the returns statement is just anything that can be in a docstring. When it comes to where the longer description should live, I also lean towards above the parameters unless it's super long. I just think that the user should be able to find the short description and the parameters/return arguments and types very quickly.

[ikrommyd]

@TaiSakuma I guess now that we have finalized the style, you can tell claude to update all similar PRs with this style.

[TaiSakuma]

This PR has been merged. Thank you, @ianna and @ikrommyd, for the review.

To recap:

• It was not possible to place text without a heading above the first heading (usually "Parameters") because that broke the rendering, as can be seen in the screenshots in docs: update ak.flatten docstring to Google style #3946 (comment). This is probably why many Awkward docstrings have text without a heading below Parameters and other sections.
• The rendering problem was fixed by docs: replace prepare_docstrings.py with sphinx-autoapi #3948. Now, Awkward docstrings can include text without a heading above the first heading without breaking rendering.