docs: description text placed under `Examples:` in some merged docstring conversions

[TaiSakuma]

The docstring conversions of the #3980 rollout restructure each docstring into summary → extended description → Args: → Returns: → Examples:. Review of PR #4139 (ariostas's comment on ak.to_buffers) found that some conversions placed main-description text under the Examples: header: the original docstrings had no example section — everything below Args: was description — and the conversion recipe moved that narrative under a newly created Examples: header instead of into the extended description. The Examples:-section checklist now defines the intended placement, and the open batch PRs are being fixed in place, but 17 already-merged files were converted before the checklist existed and need the same review.

Affected files

These are the merged files whose Examples: section was created from previously headingless narrative (found by comparing each file's pre-conversion docstring, which had no example heading, with the current one on main):

From #3986 (structural batch): ak_argcartesian.py, ak_broadcast_arrays.py, ak_broadcast_fields.py, ak_cartesian.py, ak_combinations.py, ak_pad_none.py, ak_ravel.py, ak_unflatten.py, ak_unzip.py, ak_zip.py, ak_zip_no_broadcast.py

From #4137 (from_* file/format batch): ak_from_buffers.py, ak_from_feather.py, ak_from_json.py, ak_from_regular.py

From #4140 (misc batch, merged 2026-07-22, after this issue was filed): ak_copy.py, ak_transform.py. These were found by a manual sweep rather than the heading comparison — their original docstrings already had an example heading, and description paragraphs were placed under it.

Confirmed instances so far:

• ak_from_buffers.py: the paragraphs explaining container, buffer_key, and allow_noncanonical_form sit under Examples: but are description (same situation as ak.to_buffers in the PR docs: add summary lines to 13 to_* file/format converter docstrings #4139 thread).
• ak_copy.py: the "There is an exception to this rule..." paragraph (with its embedded shallow-copy doctest) and the closing "This is key to Awkward Array's efficiency..." paragraph are description.
• ak_transform.py: the "The primary purpose of this function...", "The return value must be a subclass of #ak.contents.Content...", and "If you pass multiple arrays to this function (more_arrays)..." paragraphs are description.
• 5 files have their "See also" cross-reference line inside Examples: instead of above Args:: ak_from_feather.py, ak_from_json.py, ak_from_regular.py, ak_unflatten.py, ak_zip_no_broadcast.py.

The remaining files need a case-by-case check: an Examples: section built from headingless narrative is not automatically wrong — in some files the moved text is a genuine doctest walkthrough.

Fix

Apply the Examples:-section checklist to each file: narrative describing behavior, arguments, or history moves above Args: (relocated verbatim, only re-indented and re-wrapped); only doctest walkthroughs and their connecting prose stay under Examples:; "See also" lines go at the end of the extended description, directly above Args:. Where nothing example-like remains, the Examples: header is removed.

This is a rendering-structure fix, not only a source-layout one: on the rendered pages, the misplaced paragraphs currently appear under an "Examples" heading.

Refs #3980.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com