[shinaoka]

Covers items 2 and 3 of #149. Item 1 (a pool of width - 1 threads) is left for a threadteam decision; see below.

What changes

• Wording. The README, crate docs and with_team rustdoc examples now say "N participants: the calling thread and N-1 reserved workers" instead of "eight / four / two reserved members". The with_team rustdoc also states the participant count in prose.
• One-off use. The README, the crate docs' parallelism section and the with_team rustdoc now say that with_team is for a one-off call: every call builds a new pool, spawning its worker threads and joining them at the end. Code that runs parallel work repeatedly should own a threadteam::Pool and Team, build them once, and lend a Par from the team to each call. A short example shows this, compiled as a doctest in the rustdoc.
• Test. with_team_has_width_participants pins the current width: with_team(width) gives width participants, and into_team(4) on a pool of 3 threads gives 3.

Why item 1 is not in this PR

In threadteam 0.1.3, into_team(width) clamps width to pool.width(), which is the number of worker threads, and the leader counts toward it. A pool of width - 1 threads still accepts into_team(width), but the team has only width - 1 participants (measured: 3 threads, into_team(4) → size 3). So threads(width - 1) would narrow every with_team team by one. Saving the idle worker needs a threadteam change to how Pool::width and into_team count the leader. Until then, the pool keeps width threads, and one worker sleeps.

Verification

• All 64 faer doctests pass, including the two with_team examples.
• The new unit test passes.
• cargo doc reports the same 4 unresolved links as on main; none are new.
• Clippy reports nothing in the changed lines.

Refs #149 (not closed: item 1 remains).

🤖 Generated with Claude Code