Merge pull request #2069 from jmg-duarte/patch-1

Document <<choice>> in the state diagram page

docs/stateDiagram.md

@@ -228,6 +228,28 @@ stateDiagram-v2
 
 *You can not define transitions between internal states belonging to different composite states*
 
+## Choice
+
+Sometimes you need to model a choice between two or more paths, you can do so using <<choice>>.
+
+```
+stateDiagram-v2
+    state if_state <<choice>>
+    [*] --> IsPositive
+    IsPositive --> if_state
+    if_state --> False: if n < 0
+    if_state --> True : if n >= 0
+```
+
+```mermaid
+stateDiagram-v2
+    state if_state <<choice>>
+    [*] --> IsPositive
+    IsPositive --> if_state
+    if_state --> False: if n < 0
+    if_state --> True : if n >= 0
+```
+
 ## Forks
 
 It is possible to specify a fork in the diagram using &lt;&lt;fork&gt;&gt; &lt;&lt;join&gt;&gt;.