added addHelp() method and docs

Form/FormMapper.php

@@ -200,9 +200,22 @@ class FormMapper extends BaseGroupedMapper
     public function setHelps(array $helps = array())
     {
         foreach ($helps as $name => $help) {
-            if ($this->admin->hasFormFieldDescription($name)) {
-                $this->admin->getFormFieldDescription($name)->setHelp($help);
-            }
+            $this->addHelp($name, $help);
+        }
+
+        return $this;
+    }
+
+    /**
+     * @param $name
+     * @param $help
+     *
+     * @return FormMapper
+     */
+    public function addHelp($name, $help)
+    {
+        if ($this->admin->hasFormFieldDescription($name)) {
+            $this->admin->getFormFieldDescription($name)->setHelp($help);
         }
 
         return $this;

Resources/doc/reference/form_help_message.rst

@@ -31,8 +31,10 @@ Example
         }
     }
 
-Alternative Way To Define Help Messages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Alternative Ways To Define Help Messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+All at once
 
 .. code-block:: php
 
@@ -56,6 +58,84 @@ Alternative Way To Define Help Messages
         }
     }
 
+or step by step.
+
+.. code-block:: php
+
+    <?php
+    // src/AppBundle/Admin/PostAdmin.php
+
+    class PostAdmin extends Admin
+    {
+        protected function configureFormFields(FormMapper $formMapper)
+        {
+            $formMapper
+                ->with('General')
+                    ->add('title')
+                    ->add('keywords')
+                    ->setHelp('title', 'Set the title of a web page')
+                    ->setHelp('keywords', 'Set the keywords of a web page')
+                ->end()
+            ;
+        }
+    }
+
+This can be very useful if you want to apply general help messages via an ``AdminExtension``.
+This Extension for example adds a note field to some entities which use a custom trait.
+
+.. code-block:: php
+
+    <?php
+
+    namespace AppBundle\Admin\Extension;
+
+    use Sonata\AdminBundle\Admin\AdminExtension;
+    use Sonata\AdminBundle\Datagrid\DatagridMapper;
+    use Sonata\AdminBundle\Form\FormMapper;
+    use Sonata\AdminBundle\Show\ShowMapper;
+
+    class NoteAdminExtension extends AdminExtension
+    {
+
+        // add this field to the datagrid everytime its available
+        /**
+         * @param DatagridMapper $datagridMapper
+         */
+        public function configureDatagridFilters(DatagridMapper $datagridMapper)
+        {
+            $datagridMapper
+                ->add('note')
+            ;
+        }
+
+        // here we don't add the field, because we would like to define
+        // the place manually in the admin. But if the filed is available,
+        // we want to add the following help message to the field.
+        /**
+         * @param FormMapper $formMapper
+         */
+        public function configureFormFields(FormMapper $formMapper)
+        {
+            $formMapper
+                ->addHelp('note', 'Use this field for an internal note.')
+            ;
+        }
+
+        // if the field exists, add it in a special tab on the show view.
+        /**
+         * @param ShowMapper $showMapper
+         */
+        public function configureShowFields(ShowMapper $showMapper)
+        {
+            $showMapper
+                ->with('Internal')
+                    ->add('note')
+                ->end()
+            ;
+        }
+    }
+
+
 Help messages in a sub-field
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^