minor #12295 [Workflow] Rework a bit the doc (lyrixx)

javiereguiluz · javiereguiluz · commit a68a7c549d10 · 2019-09-24T19:56:23.000+02:00
This PR was squashed before being merged into the 3.4 branch (closes #12295). Discussion ---------- [Workflow] Rework a bit the doc  Commits ------- d48d903 [Workflow] Rework a bit the doc
diff --git a/_build/redirection_map b/_build/redirection_map
@@ -362,7 +362,8 @@
 /console/logging /console
 /frontend/encore/legacy-apps /frontend/encore/legacy-applications
 /contributing/code/patches /contributing/code/pull_requests
-/workflow/state-machines /workflow/introduction
+/workflow/state-machines /workflow/workflow-and-state-machine
+/workflow/introduction /workflow/workflow-and-state-machine
 /workflow/usage /workflow
 /introduction/from_flat_php_to_symfony2 /introduction/from_flat_php_to_symfony
 /contributing/community/other /contributing/community
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -2380,7 +2380,7 @@ type
 **type**: ``string`` **possible values**: ``'workflow'`` or ``'state_machine'``
 
 Defines the kind of workflow that is going to be created, which can be either
-a normal workflow or a state machine. Read :doc:`this article </workflow/introduction>`
+a normal workflow or a state machine. Read :doc:`this article </workflow/workflow-and-state-machine>`
 to know their differences.
 
 .. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html
diff --git a/workflow.rst b/workflow.rst
@@ -3,7 +3,7 @@ Workflow
 
 Using the Workflow component inside a Symfony application requires to know first
 some basic theory and concepts about workflows and state machines.
-:doc:`Read this article </workflow/introduction>` for a quick overview.
+:doc:`Read this article </workflow/workflow-and-state-machine>` for a quick overview.
 
 A workflow is a process or a lifecycle that your objects go through. Each
 step or stage in the process is called a *place*. You do also define *transitions*
@@ -158,13 +158,20 @@ As configured, the following property is used by the marking store::
 
     The marking store type could be "multiple_state" or "single_state". A single
     state marking store does not support a model being on multiple places at the
-    same time.
+    same time. This means a "workflow" must use a "multiple_state" marking store
+    and a "state_machine" must use a "single_state" marking store. Symfony
+    configures the marking store according to the "type" by default, so it's
+    preferable to not configure it.
+
+    A single state marking store use a string to store the data. A multiple
+    state marking store use an array to store the data.
 
 .. tip::
 
-    The ``type`` (default value ``single_state``) and ``arguments`` (default
-    value ``marking``) attributes of the ``marking_store`` option are optional.
-    If omitted, their default values will be used.
+    The ``marking_store.type`` (the default value depends on the ``type`` value)
+    and ``arguments`` (default value ``['marking']``) attributes of the
+    ``marking_store`` option are optional. If omitted, their default values will
+    be used. It's highly recommenced to use the default value.
 
 .. tip::
 
@@ -493,5 +500,5 @@ Learn more
 .. toctree::
    :maxdepth: 1
 
-   workflow/introduction
-   workflow/dumping-workflows
+   /workflow/workflow-and-state-machine
+   /workflow/dumping-workflows
diff --git a/workflow/workflow-and-state-machine.rst b/workflow/workflow-and-state-machine.rst
@@ -49,8 +49,6 @@ your model. The most important differences between them are:
 
 * Workflows can be in more than one place at the same time, whereas state
   machines can't;
-* Workflows usually don't have cyclic paths in the definition graph, but it's
-  common for state machines;
 * In order to apply a transition, workflows require that the object is in all
   the previous places of the transition, whereas state machines only require
   that the object is at least in one of those places.
