Complete Understudy API method summaries

docs/src/adapters/phpstan.md

@@ -42,7 +42,7 @@ Below level 9 there is nothing to fix here — PHPStan does not check `mixed`
 against a declared parameter — and the rest of the extension works at every
 level.
 
-The two 0.4 idioms are covered the same way: `Arg::rest()` makes the
+The two matcher idioms are covered the same way: `Arg::rest()` makes the
 `arguments.count` report go quiet wherever a call's last written argument is
 `Arg::rest()`, and `$captor->capture()` is typed `never` like the `Arg::`
 factories (the receiver's type is what decides — a foreign `capture()` is left

docs/src/adapters/psalm.md

@@ -45,7 +45,7 @@ matcher that reaches its specification through a variable, a property or a
 helper.
 :::
 
-## The two 0.4 idioms
+## The two matcher idioms
 
 - **`Arg::rest()`** legitimately passes fewer arguments than the contract
   declares, so `TooFewArguments` goes quiet on that call — but only when the

docs/src/api/classes/Arg.md

@@ -9,7 +9,7 @@ description: "Argument matchers, usable only inside a specification closure:"
 
 `Rasuvaeff\Understudy\Arg`
 
-**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Arg.php#L49) — **Version:** v0.9.0
+**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Arg.php#L49) — **Version:** v0.9.0-2-g2ad61e3
 
 Argument matchers, usable only inside a specification closure:
 
@@ -118,6 +118,8 @@ as a set: `anyOf('draft', 'review')`.
 static instanceOf(class-string $type): mixed
 ```
 
+Matches an object by its class or interface.
+
 ### captor()
 
 ```php

docs/src/api/classes/Captor.md

@@ -9,7 +9,7 @@ description: "A typed argument captor, built by Arg::captor()."
 
 `Rasuvaeff\Understudy\Captor`
 
-**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Captor.php#L38) — **Version:** v0.9.0
+**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Captor.php#L38) — **Version:** v0.9.0-2-g2ad61e3
 
 **Type parameters:**
 
@@ -88,9 +88,13 @@ Every captured value, in call order.
 record(mixed $value): void
 ```
 
+Records a value captured by a matched specification.
+
 ### discard()
 
 ```php
 discard(): void
 ```
 
+Clears values captured in a finished runtime context.
+

docs/src/api/classes/Exception/AmbiguousDefaultFactory.md

@@ -9,7 +9,7 @@ description: "Two registered default factories are equally close to the requeste
 
 `Rasuvaeff\Understudy\Exception\AmbiguousDefaultFactory`
 
-**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/AmbiguousDefaultFactory.php#L12) — **Version:** v0.9.0
+**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/AmbiguousDefaultFactory.php#L12) — **Version:** v0.9.0-2-g2ad61e3
 
 **Extends:** `LogicException`
 
@@ -28,3 +28,5 @@ static between(
 ): Exception\AmbiguousDefaultFactory
 ```
 
+Builds the error for equally close default factories.
+

docs/src/api/classes/Exception/BypassUnavailable.md

@@ -9,7 +9,7 @@ description: "`bypassFinals()` cannot do what was asked of it."
 
 `Rasuvaeff\Understudy\Exception\BypassUnavailable`
 
-**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/BypassUnavailable.php#L12) — **Version:** v0.9.0
+**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/BypassUnavailable.php#L12) — **Version:** v0.9.0-2-g2ad61e3
 
 **Extends:** `LogicException`
 
@@ -25,18 +25,24 @@ description: "`bypassFinals()` cannot do what was asked of it."
 static alreadyLoaded(class-string $class): Exception\BypassUnavailable
 ```
 
+Builds the error for a class loaded before bypass could be installed.
+
 ### notAClass()
 
 ```php
 static notAClass(class-string $class, string $kind): Exception\BypassUnavailable
 ```
 
+Builds the error for a target that is not a class.
+
 ### foreignWrapper()
 
 ```php
 static foreignWrapper(string $owner): Exception\BypassUnavailable
 ```
 
+Builds the error for an already-installed foreign source wrapper.
+
 Something else already transforms PHP source on `file://`; replacing it
 would silently disable whatever it does.
 

docs/src/api/classes/Exception/CannotWire.md

@@ -9,7 +9,7 @@ description: "`wire()` cannot build the subject, or cannot decide what to pass i
 
 `Rasuvaeff\Understudy\Exception\CannotWire`
 
-**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/CannotWire.php#L12) — **Version:** v0.9.0
+**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/CannotWire.php#L12) — **Version:** v0.9.0-2-g2ad61e3
 
 **Extends:** `InvalidArgumentException`
 
@@ -25,6 +25,8 @@ description: "`wire()` cannot build the subject, or cannot decide what to pass i
 static notAConcreteClass(string $sut, string $reason): Exception\CannotWire
 ```
 
+Builds the error for a subject that cannot be wired as a concrete class.
+
 Takes a plain string, not a `class-string`: "there is no such class" is
 one of the reasons it reports.
 
@@ -37,6 +39,8 @@ static inaccessibleConstructor(
 ): Exception\CannotWire
 ```
 
+Builds the error for an inaccessible subject constructor.
+
 ### unknownOverride()
 
 ```php
@@ -47,6 +51,8 @@ static unknownOverride(
 ): Exception\CannotWire
 ```
 
+Builds the error for an unknown constructor override.
+
 ### incompatibleOverride()
 
 ```php
@@ -58,6 +64,8 @@ static incompatibleOverride(
 ): Exception\CannotWire
 ```
 
+Builds the error for an override with an incompatible type.
+
 ### undecidableParameter()
 
 ```php
@@ -69,9 +77,13 @@ static undecidableParameter(
 ): Exception\CannotWire
 ```
 
+Builds the error for a constructor parameter with no safe answer.
+
 ### referenceParameter()
 
 ```php
 static referenceParameter(class-string $sut, string $name): Exception\CannotWire
 ```
 
+Builds the error for a by-reference constructor parameter.
+

docs/src/api/classes/Exception/ConflictingExpectation.md

@@ -9,7 +9,7 @@ description: "A `when()` or `expect()` names a call another registration already
 
 `Rasuvaeff\Understudy\Exception\ConflictingExpectation`
 
-**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/ConflictingExpectation.php#L21) — **Version:** v0.9.0
+**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/ConflictingExpectation.php#L21) — **Version:** v0.9.0-2-g2ad61e3
 
 **Extends:** `LogicException`
 
@@ -37,6 +37,8 @@ static claimAfterStub(
 ): Exception\ConflictingExpectation
 ```
 
+Builds the error for a claim registered after an identical stub.
+
 ### stubAfterCountedExpectation()
 
 ```php
@@ -46,6 +48,8 @@ static stubAfterCountedExpectation(
 ): Exception\ConflictingExpectation
 ```
 
+Builds the error for a stub registered after a counted expectation.
+
 ### duplicateCountedExpectation()
 
 ```php
@@ -55,3 +59,5 @@ static duplicateCountedExpectation(
 ): Exception\ConflictingExpectation
 ```
 
+Builds the error for duplicate counted expectations.
+

docs/src/api/classes/Exception/ContextOwnershipViolation.md

@@ -9,7 +9,7 @@ description: "Configuration and verification belong to the context that created
 
 `Rasuvaeff\Understudy\Exception\ContextOwnershipViolation`
 
-**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/ContextOwnershipViolation.php#L14) — **Version:** v0.9.0
+**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/ContextOwnershipViolation.php#L14) — **Version:** v0.9.0-2-g2ad61e3
 
 **Extends:** `LogicException`
 
@@ -28,6 +28,8 @@ make lifecycle verification race with work owned elsewhere.
 static forDouble(): Exception\ContextOwnershipViolation
 ```
 
+Builds the error for using a double from another runtime context.
+
 A double was configured or verified from a context other than the one
 that created it — another Fiber, or outside the scope it was built in.
 

docs/src/api/classes/Exception/ForgottenDouble.md

@@ -9,7 +9,7 @@ description: "A double outlived the context that created it — almost always a
 
 `Rasuvaeff\Understudy\Exception\ForgottenDouble`
 
-**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/ForgottenDouble.php#L16) — **Version:** v0.9.0
+**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/ForgottenDouble.php#L16) — **Version:** v0.9.0-2-g2ad61e3
 
 **Extends:** `LogicException`
 
@@ -29,24 +29,32 @@ non-nullable method and surface far from the actual mistake.
 static afterReset(non-empty-string $method): Exception\ForgottenDouble
 ```
 
+Builds the error for calling a double after its context was reset.
+
 ### onPurpose()
 
 ```php
 static onPurpose(non-empty-string $method): Exception\ForgottenDouble
 ```
 
+Builds the error for calling a deliberately retired double.
+
 ### propertyAfterReset()
 
 ```php
 static propertyAfterReset(non-empty-string $property): Exception\ForgottenDouble
 ```
 
+Builds the error for reading a property after reset.
+
 ### retired()
 
 ```php
 static retired(): Exception\ForgottenDouble
 ```
 
+Builds the error for asking a retired double through the facade.
+
 A facade — `strict()`, `verify()`, `nothingElse()`, `forget()` itself —
 was asked about a double that `Understudy::forget()` retired.
 
@@ -56,3 +64,5 @@ was asked about a double that `Understudy::forget()` retired.
 static fromDefaultFactory(class-string $contract): Exception\ForgottenDouble
 ```
 
+Builds the error for a default factory returning a retired double.
+

docs/src/api/classes/Exception/ForwardingTargetMismatch.md

@@ -9,7 +9,7 @@ description: "The instance offered as a forwarding target does not satisfy what
 
 `Rasuvaeff\Understudy\Exception\ForwardingTargetMismatch`
 
-**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/ForwardingTargetMismatch.php#L13) — **Version:** v0.9.0
+**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/ForwardingTargetMismatch.php#L13) — **Version:** v0.9.0-2-g2ad61e3
 
 **Extends:** `InvalidArgumentException`
 
@@ -26,6 +26,8 @@ stands in for.
 static understudyTarget(non-empty-string $label): Exception\ForwardingTargetMismatch
 ```
 
+Builds the error for forwarding to another understudy.
+
 ### missingContract()
 
 ```php
@@ -36,3 +38,5 @@ static missingContract(
 ): Exception\ForwardingTargetMismatch
 ```
 
+Builds the error for a forwarding target missing a contract.
+

docs/src/api/classes/Exception/InvalidCallSpecification.md

@@ -9,7 +9,7 @@ description: "A specification of the wrong SHAPE: the closure handed to when()/v
 
 `Rasuvaeff\Understudy\Exception\InvalidCallSpecification`
 
-**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/InvalidCallSpecification.php#L25) — **Version:** v0.9.0
+**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/InvalidCallSpecification.php#L25) — **Version:** v0.9.0-2-g2ad61e3
 
 **Extends:** `LogicException`
 
@@ -83,12 +83,16 @@ static misplacedTailMatcher(
 ): Exception\InvalidCallSpecification
 ```
 
+Builds the error for a tail matcher in the wrong position.
+
 ### emptyCombinator()
 
 ```php
 static emptyCombinator(non-empty-string $matcher): Exception\InvalidCallSpecification
 ```
 
+Builds the error for an empty matcher combinator.
+
 ### tailMatcherInCombinator()
 
 ```php
@@ -98,6 +102,8 @@ static tailMatcherInCombinator(
 ): Exception\InvalidCallSpecification
 ```
 
+Builds the error for putting a tail matcher inside a combinator.
+
 ### emptySequence()
 
 ```php
@@ -116,6 +122,8 @@ static protocolAlreadyArmed(
 ): Exception\InvalidCallSpecification
 ```
 
+Builds the error for arming a protocol while another is active.
+
 ### incompleteSpecification()
 
 ```php
@@ -126,6 +134,8 @@ static incompleteSpecification(
 ): Exception\InvalidCallSpecification
 ```
 
+Builds the error for an incomplete call specification.
+
 ### omittedBeforeSpecified()
 
 ```php
@@ -136,6 +146,8 @@ static omittedBeforeSpecified(
 ): Exception\InvalidCallSpecification
 ```
 
+Builds the error for an omitted argument before a specified one.
+
 ### omittedTailNeedsRest()
 
 ```php
@@ -145,6 +157,8 @@ static omittedTailNeedsRest(
 ): Exception\InvalidCallSpecification
 ```
 
+Builds the error for an omitted required tail without `Arg::rest()`.
+
 ### closureFailed()
 
 ```php
@@ -160,3 +174,5 @@ the original is kept as `previous`, because it is the actual mistake.
 static staticMethodCalled(non-empty-string $method): Exception\InvalidCallSpecification
 ```
 
+Builds the error for a static method used in a specification.
+

docs/src/api/classes/Exception/InvalidDefaultValue.md

@@ -9,7 +9,7 @@ description: "A registered default factory produced a value the contract cannot
 
 `Rasuvaeff\Understudy\Exception\InvalidDefaultValue`
 
-**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/InvalidDefaultValue.php#L12) — **Version:** v0.9.0
+**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/InvalidDefaultValue.php#L12) — **Version:** v0.9.0-2-g2ad61e3
 
 **Extends:** `RuntimeException`
 
@@ -28,3 +28,5 @@ static ofWrongType(
 ): Exception\InvalidDefaultValue
 ```
 
+Builds the error for a factory value with the wrong type.
+

docs/src/api/classes/Exception/InvalidSpecificationArgument.md

@@ -9,7 +9,7 @@ description: "A VALUE inside a specification that no run could act on: a maximum
 
 `Rasuvaeff\Understudy\Exception\InvalidSpecificationArgument`
 
-**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/InvalidSpecificationArgument.php#L24) — **Version:** v0.9.0
+**Class** — **Package:** [rasuvaeff/understudy](https://github.com/rasuvaeff/understudy) — [Source](https://github.com/rasuvaeff/understudy/blob/master/src/Exception/InvalidSpecificationArgument.php#L24) — **Version:** v0.9.0-2-g2ad61e3
 
 **Extends:** `InvalidArgumentException`