Change all content from rst format to markdown and correct spelling/grammar

docs/source/development/embeddable-comments.md

@@ -0,0 +1,97 @@
+# Embeddable comments
+
+Those embeddable comments is a comment with some metadata:
+
+* the one who updated the comment (the comment itself, and not the whole entity);
+* the date and time for the last update (again, the comment itself, and not the whole entity).
+
+We make usage of [embeddable ](https://www.doctrine-project.org/projects/doctrine-orm/en/2.8/tutorials/embeddables.html).
+
+## Embed the comment
+
+The comment may be embedded into the entity:
+
+```php
+   namespace Chill\ActivityBundle\Entity;
+
+   use Chill\MainBundle\Entity\Embeddable\CommentEmbeddable;
+   use Doctrine\ORM\Mapping as ORM;
+
+   /**
+    * Class Activity
+    *
+    * @ORM\Entity()
+    */
+   class Activity
+   {
+       /**
+        * @var integer
+        *
+        * @ORM\Id
+        * @ORM\Column(name="id", type="integer")
+        * @ORM\GeneratedValue(strategy="AUTO")
+        */
+       private $id;
+
+       /**
+        * @ORM\Embedded(class="Chill\MainBundle\Entity\Embeddable\CommentEmbeddable", columnPrefix="comment_")
+        */
+       private $comment;
+
+       /**
+        * @return \Chill\MainBundle\Entity\Embeddalbe\CommentEmbeddable
+        */
+       public function getComment()
+       {
+           return $this->comment;
+       }
+
+       /**
+        * @param \Chill\MainBundle\Entity\Embeddalbe\CommentEmbeddable $comment
+        */
+       public function setComment($comment)
+       {
+           $this->comment = $comment;
+       }
+   }
+```
+
+## Note on relation to :class:`User`
+
+The embeddable proposed by Doctrine does not support relationship to other entities. The entity Comment is able to render a user's id, but not an User object.
+
+   `$activity->getComment()->getUserId(); // return user id of the last author`
+
+   `$activity->getComment()->getUser(); // does not work !`
+
+## Usage into form
+
+Use the `Chill\MainBundle\Form\Type\CommentType` to load the form widget:
+
+```php
+   namespace Chill\ActivityBundle\Form;
+
+   use Chill\MainBundle\Form\Type\CommentType;
+   use Symfony\Component\Form\AbstractType;
+   use Symfony\Component\Form\FormBuilderInterface;
+
+   class ActivityType extends AbstractType
+   {
+       /**
+        * @param FormBuilderInterface $builder
+        * @param array $options
+        */
+       public function buildForm(FormBuilderInterface $builder, array $options)
+       {
+           $builder
+               ->add('comment', CommentType::class, [
+                   'required' => false,
+               ])
+           ;
+       }
+   }
+```
+
+## Render the comment
+
+   `{{ activity.comment|chill_entity_render_box }}`