[#2504] Tweaks to new Process signal and pid docs

Author: weaverryan

components/process.rst

@@ -98,20 +98,22 @@ are done doing other stuff::
 
 .. note::
 
-    Please consider that the :method:`Symfony\\Component\\Process\\Process::wait`
-    method is blocking.
+    The :method:`Symfony\\Component\\Process\\Process::wait` method is blocking,
+    which means that your code will halt at this line until the external
+    process is completed.
+
+Stopping a Process
+~~~~~~~~~~~~~~~~~~
 
 .. versionadded:: 2.3
     The ``signal`` parameter of the ``stop`` method was added in Symfony 2.3.
 
 Any asynchronous process can be stopped at any time with the
 :method:`Symfony\\Component\\Process\\Process::stop` method. This method takes
 two arguments : a timeout and a signal. Once the timeout is reached, the signal
-is sent to the running process.
-The default signal sent to a process is ``SIGKILL``. Please read the signal
-documentation below to know more about signal handling in the Process component.
-
-.. code-block:: php
+is sent to the running process. The default signal sent to a process is ``SIGKILL``.
+Please read the :ref:`signal documentation below<reference-process-signal>`
+to find out more about signal handling in the Process component::
 
     $process = new Process('ls -lsa');
     $process->start();
@@ -172,16 +174,16 @@ check regularly::
         usleep(200000);
     }
 
+.. _reference-process-signal:
+
 Process Signals
 ---------------
 
 .. versionadded:: 2.3
     The ``signal`` method was added in Symfony 2.3.
 
-When running programs asynchronously, you can send it posix signals with the
-:method:`Symfony\\Component\\Process\\Process::signal` method.
-
-.. code-block:: php
+When running a program asynchronously, you can send it posix signals with the
+:method:`Symfony\\Component\\Process\\Process::signal` method::
 
     use Symfony\Component\Process\Process;
 
@@ -195,7 +197,7 @@ When running programs asynchronously, you can send it posix signals with the
 
     Due to some limitations in PHP, if you're using signals with the Process
     component, you may have to prefix your commands with `exec`_. Please read
-    `Symfony Issue#5769`_ and `PHP Bug#39992`_ to understand why this is happening.
+    `Symfony Issue#5759`_ and `PHP Bug#39992`_ to understand why this is happening.
 
     POSIX signals are not available on Windows platforms, please refer to the
     `PHP documentation`_ for available signals.
@@ -222,11 +224,11 @@ You can access the `pid`_ of a running process with the
 
     Due to some limitations in PHP, if you want to get the pid of a symfony Process,
     you may have to prefix your commands with `exec`_. Please read
-    `Symfony Issue#5769`_ to understand why this is happening.
+    `Symfony Issue#5759`_ to understand why this is happening.
 
-.. _Symfony Issue#5759: https://github.com/symfony/symfony/issues/5759
-.. _PHP Bug#39992: https://bugs.php.net/bug.php?id=39992
-.. _exec: http://en.wikipedia.org/wiki/Exec_(operating_system)
-.. _pid: http://en.wikipedia.org/wiki/Process_identifier
-.. _PHP Documentation: http://php.net/manual/en/pcntl.constants.php
+.. _`Symfony Issue#5759`: https://github.com/symfony/symfony/issues/5759
+.. _`PHP Bug#39992`: https://bugs.php.net/bug.php?id=39992
+.. _`exec`: http://en.wikipedia.org/wiki/Exec_(operating_system)
+.. _`pid`: http://en.wikipedia.org/wiki/Process_identifier
+.. _`PHP Documentation`: http://php.net/manual/en/pcntl.constants.php
 .. _Packagist: https://packagist.org/packages/symfony/process