Merge pull request #291 from FriendsOfSymfony/improve-doc

Adapt and improve the documentation for new features and new best practices
FriendsOfSymfony · Sep 7, 2016 · 281fd99 · 281fd99
2 parents 801398b + ec03ddb
commit 281fd99
Show file tree

Hide file tree

Showing 12 changed files with 192 additions and 131 deletions.
diff --git a/README.md b/README.md
@@ -16,15 +16,15 @@ Documentation
 
 Documentation for this bundle is stored under `Resources/doc` in this repository.
 
-[Read the documentation for master][]
+[Read the documentation for the last stable (1.3)][]
 
 License
 -------
 
 This bundle is under the MIT license. See the complete license in the bundle:
 
 ```
-    Resources/meta/LICENSE
+Resources/meta/LICENSE
 ```
 
-[Read the documentation for master]: https://github.com/FriendsOfSymfony/FOSMessageBundle/blob/master/Resources/doc/00-index.md
+[Read the documentation for the last stable (1.3)]: https://github.com/FriendsOfSymfony/FOSMessageBundle/blob/master/Resources/doc/00-index.md
diff --git a/Resources/doc/01-installation.md b/Resources/doc/01-installation.md
@@ -11,7 +11,7 @@ The first step is to tell composer that you want to download FOSMessageBundle wh
 be achieved by typing the following at the command prompt:
 
 ```bash
-$ php composer.phar require friendsofsymfony/message-bundle
+$ composer require friendsofsymfony/message-bundle
 ```
 
 ### Step 2 - Setting up your user class
@@ -24,6 +24,7 @@ Your user class may look something like the following:
 
 ```php
 <?php
+// src/AppBundle/Entity/User.php
 
 use Doctrine\ORM\Mapping as ORM;
 use FOS\MessageBundle\Model\ParticipantInterface;
@@ -52,7 +53,7 @@ We provide examples for both Mongo DB and ORM.
 The bundle must be added to your `AppKernel`
 
 ```php
-# app/AppKernel.php
+// app/AppKernel.php
 
 public function registerBundles()
 {
@@ -71,11 +72,9 @@ Add FOSMessageBundle's routing to your application with an optional routing pref
 ```yaml
 # app/config/routing.yml
 
-# ...
 fos_message:
     resource: "@FOSMessageBundle/Resources/config/routing.xml"
     prefix: /optional_routing_prefix
-# ...
 ```
 
 ## Installation Finished

diff --git a/Resources/doc/01a-orm-models.md b/Resources/doc/01a-orm-models.md
@@ -14,8 +14,8 @@ Add the following to your `app/config/config.yml` file.
 
 fos_message:
     db_driver: orm
-    thread_class: Acme\MessageBundle\Entity\Thread
-    message_class: Acme\MessageBundle\Entity\Message
+    thread_class: AppBundle\Entity\Thread
+    message_class: AppBundle\Entity\Message
 ```
 
 [Continue with the installation][]
@@ -25,12 +25,12 @@ Message class
 
 ```php
 <?php
-// src/Acme/MessageBundle/Entity/Message.php
+// src/AppBundle/Entity/Message.php
 
-namespace Acme\MessageBundle\Entity;
+namespace AppBundle\Entity;
 
 use Doctrine\ORM\Mapping as ORM;
-use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
 use FOS\MessageBundle\Entity\Message as BaseMessage;
 
 /**
@@ -47,26 +47,26 @@ class Message extends BaseMessage
 
     /**
      * @ORM\ManyToOne(
-     *   targetEntity="Acme\MessageBundle\Entity\Thread",
+     *   targetEntity="AppBundle\Entity\Thread",
      *   inversedBy="messages"
      * )
      * @var \FOS\MessageBundle\Model\ThreadInterface
      */
     protected $thread;
 
     /**
-     * @ORM\ManyToOne(targetEntity="Acme\UserBundle\Entity\User")
+     * @ORM\ManyToOne(targetEntity="AppBundle\Entity\User")
      * @var \FOS\MessageBundle\Model\ParticipantInterface
      */
     protected $sender;
 
     /**
      * @ORM\OneToMany(
-     *   targetEntity="Acme\MessageBundle\Entity\MessageMetadata",
+     *   targetEntity="AppBundle\Entity\MessageMetadata",
      *   mappedBy="message",
      *   cascade={"all"}
      * )
-     * @var MessageMetadata[]|\Doctrine\Common\Collections\Collection
+     * @var MessageMetadata[]|Collection
      */
     protected $metadata;
 }
@@ -77,9 +77,9 @@ MessageMetadata class
 
 ```php
 <?php
-// src/Acme/MessageBundle/Entity/MessageMetadata.php
+// src/AppBundle/Entity/MessageMetadata.php
 
-namespace Acme\MessageBundle\Entity;
+namespace AppBundle\Entity;
 
 use Doctrine\ORM\Mapping as ORM;
 use FOS\MessageBundle\Entity\MessageMetadata as BaseMessageMetadata;
@@ -98,15 +98,15 @@ class MessageMetadata extends BaseMessageMetadata
 
     /**
      * @ORM\ManyToOne(
-     *   targetEntity="Acme\MessageBundle\Entity\Message",
+     *   targetEntity="AppBundle\Entity\Message",
      *   inversedBy="metadata"
      * )
      * @var \FOS\MessageBundle\Model\MessageInterface
      */
     protected $message;
 
     /**
-     * @ORM\ManyToOne(targetEntity="Acme\UserBundle\Entity\User")
+     * @ORM\ManyToOne(targetEntity="AppBundle\Entity\User")
      * @var \FOS\MessageBundle\Model\ParticipantInterface
      */
     protected $participant;
@@ -118,12 +118,12 @@ Thread class
 
 ```php
 <?php
-// src/Acme/MessageBundle/Entity/Thread.php
+// src/AppBundle/Entity/Thread.php
 
-namespace Acme\MessageBundle\Entity;
+namespace AppBundle\Entity;
 
 use Doctrine\ORM\Mapping as ORM;
-use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
 use FOS\MessageBundle\Entity\Thread as BaseThread;
 
 /**
@@ -139,27 +139,27 @@ class Thread extends BaseThread
     protected $id;
 
     /**
-     * @ORM\ManyToOne(targetEntity="Acme\UserBundle\Entity\User")
+     * @ORM\ManyToOne(targetEntity="AppBundle\Entity\User")
      * @var \FOS\MessageBundle\Model\ParticipantInterface
      */
     protected $createdBy;
 
     /**
      * @ORM\OneToMany(
-     *   targetEntity="Acme\MessageBundle\Entity\Message",
+     *   targetEntity="AppBundle\Entity\Message",
      *   mappedBy="thread"
      * )
-     * @var Message[]|\Doctrine\Common\Collections\Collection
+     * @var Message[]|Collection
      */
     protected $messages;
 
     /**
      * @ORM\OneToMany(
-     *   targetEntity="Acme\MessageBundle\Entity\ThreadMetadata",
+     *   targetEntity="AppBundle\Entity\ThreadMetadata",
      *   mappedBy="thread",
      *   cascade={"all"}
      * )
-     * @var ThreadMetadata[]|\Doctrine\Common\Collections\Collection
+     * @var ThreadMetadata[]|Collection
      */
     protected $metadata;
 }
@@ -170,9 +170,9 @@ ThreadMetadata class
 
 ```php
 <?php
-// src/Acme/MessageBundle/Entity/ThreadMetadata.php
+// src/AppBundle/Entity/ThreadMetadata.php
 
-namespace Acme\MessageBundle\Entity;
+namespace AppBundle\Entity;
 
 use Doctrine\ORM\Mapping as ORM;
 use FOS\MessageBundle\Entity\ThreadMetadata as BaseThreadMetadata;
@@ -191,15 +191,15 @@ class ThreadMetadata extends BaseThreadMetadata
 
     /**
      * @ORM\ManyToOne(
-     *   targetEntity="Acme\MessageBundle\Entity\Thread",
+     *   targetEntity="AppBundle\Entity\Thread",
      *   inversedBy="metadata"
      * )
      * @var \FOS\MessageBundle\Model\ThreadInterface
      */
     protected $thread;
 
     /**
-     * @ORM\ManyToOne(targetEntity="Acme\UserBundle\Entity\User")
+     * @ORM\ManyToOne(targetEntity="AppBundle\Entity\User")
      * @var \FOS\MessageBundle\Model\ParticipantInterface
      */
     protected $participant;

diff --git a/Resources/doc/01b-odm-models.md b/Resources/doc/01b-odm-models.md
@@ -14,8 +14,8 @@ Add the following to your `app/config/config.yml` file.
 
 fos_message:
     db_driver: mongodb
-    thread_class: Acme\MessageBundle\Document\Thread
-    message_class: Acme\MessageBundle\Document\Message
+    thread_class: AppBundle\Document\Thread
+    message_class: AppBundle\Document\Message
 ```
 
 You may have to include the MessageBundle in your Doctrine mapping configuration,
@@ -39,9 +39,9 @@ Message class
 
 ```php
 <?php
-// src/Acme/MessageBundle/Document/Message.php
+// src/AppBundle/Document/Message.php
 
-namespace Acme\MessageBundle\Document;
+namespace AppBundle\Document;
 
 use Doctrine\ODM\MongoDB\Mapping\Annotations as MongoDB;
 use FOS\MessageBundle\Document\Message as BaseMessage;
@@ -57,17 +57,17 @@ class Message extends BaseMessage
     protected $id;
 
     /**
-     * @MongoDB\EmbedMany(targetDocument="Acme\MessageBundle\Document\MessageMetadata")
+     * @MongoDB\EmbedMany(targetDocument="AppBundle\Document\MessageMetadata")
      */
     protected $metadata;
 
     /**
-     * @MongoDB\ReferenceOne(targetDocument="Acme\MessageBundle\Document\Thread")
+     * @MongoDB\ReferenceOne(targetDocument="AppBundle\Document\Thread")
      */
     protected $thread;
 
     /**
-     * @MongoDB\ReferenceOne(targetDocument="Acme\UserBundle\Document\User")
+     * @MongoDB\ReferenceOne(targetDocument="AppBundle\Document\User")
      */
     protected $sender;
 }
@@ -78,8 +78,9 @@ MessageMetadata class
 
 ```php
 <?php
+// src/AppBundle/Document/MessageMetadata.php
 
-namespace Mashup\MessageBundle\Document;
+namespace AppBundle\Document;
 
 use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
 use FOS\MessageBundle\Document\MessageMetadata as BaseMessageMetadata;
@@ -90,7 +91,7 @@ use FOS\MessageBundle\Document\MessageMetadata as BaseMessageMetadata;
 class MessageMetadata extends BaseMessageMetadata
 {
     /**
-     * @ODM\ReferenceOne(targetDocument="Mashup\UserBundle\Document\User")
+     * @ODM\ReferenceOne(targetDocument="AppBundle\Document\User")
      */
     protected $participant;
 }
@@ -101,9 +102,9 @@ Thread class
 
 ```php
 <?php
-// src/Acme/MessageBundle/Document/Thread.php
+// src/AppBundle/Document/Thread.php
 
-namespace Acme\MessageBundle\Document;
+namespace AppBundle\Document;
 
 use Doctrine\ODM\MongoDB\Mapping\Annotations as MongoDB;
 use FOS\MessageBundle\Document\Thread as BaseThread;
@@ -119,22 +120,22 @@ class Thread extends BaseThread
     protected $id;
 
     /**
-     * @MongoDB\ReferenceMany(targetDocument="Acme\MessageBundle\Document\Message")
+     * @MongoDB\ReferenceMany(targetDocument="AppBundle\Document\Message")
      */
     protected $messages;
 
     /**
-     * @MongoDB\EmbedMany(targetDocument="Acme\MessageBundle\Document\ThreadMetadata")
+     * @MongoDB\EmbedMany(targetDocument="AppBundle\Document\ThreadMetadata")
      */
     protected $metadata;
 
     /**
-     * @MongoDB\ReferenceMany(targetDocument="Acme\UserBundle\Document\User")
+     * @MongoDB\ReferenceMany(targetDocument="AppBundle\Document\User")
      */
     protected $participants;
 
     /**
-     * @MongoDB\ReferenceOne(targetDocument="Acme\UserBundle\Document\User")
+     * @MongoDB\ReferenceOne(targetDocument="AppBundle\Document\User")
      */
     protected $createdBy;
 }
@@ -145,8 +146,9 @@ ThreadMetadata class
 
 ```php
 <?php
+// src/AppBundle/Document/ThreadMetadata.php
 
-namespace Mashup\MessageBundle\Document;
+namespace AppBundle\Document;
 
 use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
 use FOS\MessageBundle\Document\ThreadMetadata as BaseThreadMetadata;
@@ -157,7 +159,7 @@ use FOS\MessageBundle\Document\ThreadMetadata as BaseThreadMetadata;
 class ThreadMetadata extends BaseThreadMetadata
 {
     /**
-     * @ODM\ReferenceOne(targetDocument="Mashup\UserBundle\Document\User")
+     * @ODM\ReferenceOne(targetDocument="AppBundle\Document\User")
      */
     protected $participant;
 }