updated documentation

closes #17

Author: narfdotpl

HISTORY.md

@@ -1,6 +1,13 @@
 ## [0.3.0][] • work in progress
 
 - Updated to Swift 2.1 (Xcode 7.1).
+
+- Made references to class-based subjects weak.  This helps to remove
+  subject-machine reference cycles, but it also means you have to keep a
+  strong reference to a subject somewhere else (which you usually already do).
+  When subject references become `nil`, transitions are no longer performed.
+  Thanks to @bartekchlebek for work on this issue! :clap:
+
 - Added default `DOTLabel` implementation (`return "\(self)"`).  You don't
   have to change anything.  If you have custom `DOTLabel` implementations,
   you can keep using them, but if the only thing you do is `case Foo: return

README.md

@@ -277,7 +277,14 @@ Enjoy improving your code by explicitly defining distinct states and
 transitions between them!  While you do so, please keep two things in
 mind:
 
-1) Remember that [Swift `enum`s][enums] can have associated values — you
+1) Your subjects are probably reference types (classes).  Storing a
+state machine as a property of a subject normally would create a reference
+cycle, so SwiftyStateMachine uses weak references for class-based subjects.
+This means you have to keep a strong reference to a subject somewhere else,
+but you usually already do this.  When subject references become `nil`,
+transitions are no longer performed.
+
+2) Remember that [Swift `enum`s][enums] can have associated values — you
 can pass additional information with events or store data in states.
 For example, if you had a game with a [heads-up display][HUD], you could
 do something like this:
@@ -297,22 +304,6 @@ machine.handleEvent(.TakeDamage(13.37))
   [HUD]: http://en.wikipedia.org/wiki/HUD_%28video_gaming%29
 
 
-2) If your subjects are reference types (classes), remember to use `unowned`
-to break reference cycles:
-
-```swift
-let schema = // ...
-
-class MyViewController: UIViewController {
-    lazy var stateMachine = { [unowned self] in
-       StateMachine(schema: schema, subject: self)
-    }()
-
-    // ...
-}
-```
-
-
 Development
 -----------
 

StateMachine/StateMachine.swift

@@ -51,6 +51,11 @@ public struct StateMachineSchema<A, B, C>: StateMachineSchemaType {
 /// `StateMachineSchemaType` documentation for more information about schemas
 /// and subjects.
 ///
+/// References to class-based subjects are weak.  This helps to remove 
+/// subject-machine reference cycles, but it also means you have to keep a
+/// strong reference to a subject somewhere else.  When subject references
+/// become `nil`, transitions are no longer performed.
+///
 /// The state machine provides the `state` property for inspecting the current
 /// state and the `handleEvent` method for triggering state transitions
 /// defined in the schema.
@@ -83,7 +88,8 @@ public final class StateMachine<T: StateMachineSchemaType> {
     }
 
     /// A method for triggering transitions and changing the state of the
-    /// machine.  If the transition logic of the schema defines a transition
+    /// machine.  Transitions are not performed when a weak reference to the subject
+    /// becomes `nil`.  If the transition logic of the schema defines a transition
     /// for current state and given event, the state is changed, the optional
     /// transition block is executed, and `didTransitionCallback` is called.
     public func handleEvent(event: T.Event) {
@@ -104,6 +110,10 @@ public final class StateMachine<T: StateMachineSchemaType> {
 
 
 public extension StateMachine where T.Subject: AnyObject {
+    /// Creates a state machine with a weak reference to a subject.  This helps
+    /// to remove subject-machine reference cycles, but it also means you have 
+    /// to keep a strong reference to a subject somewhere else.  When subject 
+    /// reference becomes `nil`, transitions are no longer performed.
     public convenience init(schema: T, subject: T.Subject) {
         self.init(schema: schema, subject: { [weak subject] in subject })
     }

StateMachineTests/StateMachineSpec.swift

@@ -57,7 +57,7 @@ private class Subject {
     typealias SchemaType = StateMachineSchema<SimpleState, SimpleEvent, Subject>
 
     let schema: SchemaType
-    lazy var machine: StateMachine<SchemaType> = { [unowned self] in
+    lazy var machine: StateMachine<SchemaType> = { 
         StateMachine(schema: self.schema, subject: self)
     }()