Skip to content

Commit 9d2b921

Browse files
committed
WIP: Update prose to match new code.
1 parent 1132491 commit 9d2b921

File tree

1 file changed

+13
-29
lines changed

1 file changed

+13
-29
lines changed

TSPL.docc/LanguageGuide/Protocols.md

Lines changed: 13 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -823,7 +823,9 @@ Delegation can be used to respond to a particular action,
823823
or to retrieve data from an external source without needing to know
824824
the underlying type of that source.
825825

826-
The example below defines two protocols for use with dice-based board games:
826+
The example below defines a dice game
827+
and a nested protocol for a delegate
828+
that tracks the game's progress.
827829

828830
```swift
829831
class DiceGame {
@@ -863,9 +865,16 @@ class DiceGame {
863865
}
864866
```
865867

866-
The `DiceGame` class implements a simple game using dice.
868+
The `DiceGame` class implements a game where
869+
each player takes a turn rolling dice,
870+
and the player who rolls the highest number wins the round.
871+
It uses a linear congruential generator,
872+
from the example earlier in the chapter,
873+
to generate random numbers for dice rolls.
874+
875+
867876
The `DiceGame.Delegate` protocol can be adopted
868-
to track the progress of this game.
877+
to track the progress of a dice game.
869878
Because the `DiceGame.Delegate` protocol
870879
is always used in the context of a dice game,
871880
it's nested inside of the `DiceGame` protocol.
@@ -874,42 +883,17 @@ inside of type declarations like structures and classes,
874883
as long as the outer declaration isn't generic.
875884
For information about nesting types, see <doc:NestedTypes>.
876885

877-
<!-- XXX delete forward reference? -->
878886
To prevent strong reference cycles,
879887
delegates are declared as weak references.
880888
For information about weak references,
881889
see <doc:AutomaticReferenceCounting#Strong-Reference-Cycles-Between-Class-Instances>.
882890
Marking the protocol as class-only
883-
lets the `SnakesAndLadders` class later in this chapter
891+
lets the `DiceGame` class
884892
declare that its delegate must use a weak reference.
885893
A class-only protocol
886894
is marked by its inheritance from `AnyObject`,
887895
as discussed in <doc:Protocols#Class-Only-Protocols>.
888896

889-
<!-- XXX rewrite paragraph -->
890-
This version of the game is wrapped up as a class called `SnakesAndLadders`,
891-
which adopts the `DiceGame` protocol.
892-
It provides a gettable `dice` property and a `play()` method
893-
in order to conform to the protocol.
894-
(The `dice` property is declared as a constant property
895-
because it doesn't need to change after initialization,
896-
and the protocol only requires that it must be gettable.)
897-
898-
<!-- XXX rewrite paragraph -->
899-
The *Snakes and Ladders* game board setup takes place within
900-
the class's `init()` initializer.
901-
All game logic is moved into the protocol's `play` method,
902-
which uses the protocol's required `dice` property to provide its dice roll values.
903-
904-
<!-- XXX rewrite paragraph -->
905-
Note that the `delegate` property is defined as an *optional* `DiceGame.Delegate`,
906-
because a delegate isn't required in order to play the game.
907-
Because it's of an optional type,
908-
the `delegate` property is automatically set to an initial value of `nil`.
909-
Thereafter, the game instantiator has the option to set the property to a suitable delegate.
910-
Because the `DiceGame.Delegate` protocol is class-only, you can declare the
911-
delegate to be `weak` to prevent reference cycles.
912-
913897
`DiceGame.Delegate` provides three methods for tracking the progress of a game.
914898
These three methods have been incorporated into the game logic within
915899
the `play()` method above, and are called when

0 commit comments

Comments
 (0)