[TexasCoding]

Summary

Docstring-only sweep that closes Round-3 audit findings about sync/async docstring drift on the resource classes. Every async *_all iterator-factory method now carries the same one-line marker telling callers to use async for (not await); the two async portfolio methods that had abbreviated docstrings relative to their sync counterparts now carry the same prose; and one stale type reference (FixedPointDollars) in the CreateOrderV2Request docstring is replaced with the real Python alias (DollarDecimal).

Issues closed

• Closes Async *_all iterator-factory methods inconsistently document their non-awaitable return contract #334 — async *_all iterator-factory marker docstrings standardized across orders/markets/portfolio/communications
• Closes Async positions_all omits the event_positions caveat present on the sync docstring #337 — AsyncPortfolioResource.positions_all carries the event_positions caveat
• Closes Async total_resting_order_value docstring drops the FCM/403/demo-parity note the sync has #338 — AsyncPortfolioResource.total_resting_order_value carries the FCM/403/demo-parity note
• Closes CreateOrderV2Request docstring references nonexistent FixedPointDollars Python type #339 — CreateOrderV2Request docstring references DollarDecimal (the real alias) instead of the nonexistent FixedPointDollars

Behavioral changes

None — docstrings only. No signatures, no imports, no runtime behavior touched.

Tests

None added — docstring-only PR. ruff and mypy pass clean on the touched files.

Source

Round-3 independent audit closure plan, wave W0.

[claude]

Code Review

Summary: Docstring-only sweep closing Round-3 audit findings (#334, #337, #338, #339). No behavioral changes; all four targeted issues are addressed correctly.

---

What looks good

• CreateOrderV2Request fix — FixedPointDollars → DollarDecimal is correct; FixedPointDollars has never existed as a public alias, so this prevents user confusion.
• positions_all expansion — The event_positions caveat is substantive and now matches the sync counterpart verbatim. This is the most valuable change in the PR.
• total_resting_order_value expansion — FCM/403/demo-parity note now consistent between sync and async.
• Standardized iterator marker — """Returns an async iterator — use ``async for``.""" is a clean, consistent one-liner across orders/markets/portfolio/communications.
• All changes are surgical; no signature, import, or runtime behavior touched.

---

Issues

Minor: positions_all async docstring is missing one sentence from the sync version

The sync PortfolioResource.positions_all (line 116–124) opens with:

"""Auto-paginate ``/portfolio/positions``, yielding each ``MarketPosition``.

Mirrors :meth:`settlements_all`. The endpoint response also carries …

The async version added by this PR opens with:

"""Async counterpart of :meth:`PortfolioResource.positions_all`. Use ``async for``.

The endpoint response also carries …

The Mirrors :meth:settlements_all. sentence is dropped. It's a minor omission — callers reading only the async docstring lose the cross-reference hint — but given the PR's stated goal of parity it's worth noting.

Observation: Several async iterator methods outside this PR's scope still lack the standard docstring

This isn't a blocker for the targeted issues (#334), but for reference, the following methods don't yet carry the marker (or any docstring):

File	Method
historical.py	All four async *_all methods (lines 361, 437, 483, 531) — no docstring at all
events.py	Both async list_all / list_all_series methods (lines 243, 294) — no docstring
multivariate.py	Async list_all (line 320) — no docstring
subaccounts.py	Async transfers_all (line 310) — only a # Plain def comment, no docstring

These are plausibly Round-4 material if the audit continues.

Nitpick: hardcoded audit reference in total_resting_order_value

"""… demo mirrors prod on this route per Path B audit (2026-04-18)."""

The date and "Path B audit" label are internal provenance that won't mean anything to an SDK consumer reading the rendered docs. It's already in the sync docstring so this PR just copies it — fine for now — but worth cleaning up when the sync version is next touched.

---

Verdict

The four targeted issues are fixed correctly and the changes are minimal. The positions_all missing sentence is a small gap worth fixing before merge; everything else is observational. Approve after addressing that one sentence.

[TexasCoding]

Round-2 review addressed in 83a227f:

• Restored Mirrors :meth:settlements_all. cross-reference on AsyncPortfolioResource.positions_all so it now parallels the sync docstring.

Deferred (not addressed in this PR):

• Other async iterator methods outside the orders/portfolio/communications scope of this PR (historical/events/multivariate/subaccounts) — out of scope; can follow up in a separate issue.
• Hardcoded Path B audit (2026-04-18) date — this PR only copied the existing line from sync, and the bot itself noted "fine for now".

[claude]

Code Review — PR #360: sync/async resource docstring drift sweep

Verdict: Approve with minor suggestions. Clean, well-scoped, no runtime risk.

---

Overview

Docstring-only PR closing four tracked issues:

• CreateOrderV2Request docstring references nonexistent FixedPointDollars Python type #339 — FixedPointDollars → DollarDecimal in CreateOrderV2Request docstring (correctness fix, not just style)
• Async *_all iterator-factory methods inconsistently document their non-awaitable return contract #334 — Standard """Returns an async iterator — use ``async for``.""" marker added to orders.fills_all, communications.list_all_rfqs/list_all_quotes, portfolio.settlements_all
• Async positions_all omits the event_positions caveat present on the sync docstring #337 — AsyncPortfolioResource.positions_all gets the event_positions design-decision caveat
• Async total_resting_order_value docstring drops the FCM/403/demo-parity note the sync has #338 — AsyncPortfolioResource.total_resting_order_value documents the FCM/403 behavior

All affected files confirm the changes look correct in context.

---

Positive

• FixedPointDollars fix is correct. FixedPointDollars is not an exported type anywhere in the codebase — DollarDecimal is the real alias (backed by types.py). This was actively misleading.
• positions_all expanded docstring adds real value. The explanation of why event_positions is not surfaced (page boundaries make event-level aggregates meaningless) is a genuine design decision that callers would otherwise hit through trial and error. Good prose.
• total_resting_order_value 403 note is useful. Non-FCM accounts will get a hard error; documenting that upfront saves a debugging session.
• Standardized one-liner is clean. """Returns an async iterator — use ``async for``.""" is concise and consistent across the touched methods.

---

Minor concerns

1. Internal audit reference in total_resting_order_value docstring (nit)

# current
"""Total value of resting orders in cents. FCM-members only.

Non-FCM accounts receive 403; demo mirrors prod on this route
per Path B audit (2026-04-18).
"""

per Path B audit (2026-04-18) is internal process jargon that means nothing to SDK users reading generated docs. The observable behavior (Non-FCM accounts receive 403; demo mirrors prod) is what matters. Consider dropping the audit attribution:

"""Total value of resting orders in cents. FCM-members only.

Non-FCM accounts receive 403. Demo mirrors prod on this route.
"""

2. "Mirrors :meth:settlements_all" cross-reference is now misleading (nit)

positions_all says "Mirrors :meth:settlements_all" at the top, implying documentation parity — but settlements_all now only carries the minimal one-liner. A reader following the cross-ref gets nothing useful. Either drop the Mirrors sentence or expand settlements_all similarly.

3. Remaining async-iterator methods without the marker (out of scope, but worth tracking)

This sweep covers orders/markets/portfolio/communications. Four resource files still have async _all / iterator-factory methods with no async for marker docstring:

• historical.py — 4 methods (fills_all, list_all for markets, orders, trades)
• events.py — 2 methods (list_all, list_all_multivariate)
• multivariate.py — 1 method (list_all)
• subaccounts.py — 1 method (list_all_transfers, currently has an inline # comment instead)

If those aren't covered by existing open issues, worth filing a follow-up rather than leaving the audit incomplete.

---

Summary

The DollarDecimal correction is the most important change here — a wrong type name in a docstring actively misleads callers. The rest is solid parity work. Address the audit-reference nit and the Mirrors cross-ref before merge if convenient, but neither is a blocker.