doc(newsletters): improve documentation in the Newsletters package

app/TeenQuotes/Newsletters/Console/SendNewsletterCommand.php

@@ -35,17 +35,18 @@ class SendNewsletterCommand extends ScheduledCommand
     private $possibleTypes = ['daily', 'weekly'];
 
     /**
-     * @var \TeenQuotes\Quotes\Repositories\QuoteRepository
+     * @var QuoteRepository
      */
     private $quoteRepo;
 
     /**
-     * @var \TeenQuotes\Newsletters\NewsletterList
+     * @var NewsletterList
      */
     private $newsletterList;
 
     /**
-     * Create a new command instance.
+     * @param QuoteRepository $quoteRepo
+     * @param NewsletterList  $newsletterList
      */
     public function __construct(QuoteRepository $quoteRepo, NewsletterList $newsletterList)
     {
@@ -58,7 +59,7 @@ public function __construct(QuoteRepository $quoteRepo, NewsletterList $newslett
     /**
      * When a command should run.
      *
-     * @param  \Indatus\Dispatcher\Scheduling\Schedulable
+     * @param Schedulable
      *
      * @return array
      */
@@ -113,21 +114,41 @@ public function fire()
         }
     }
 
+    /**
+     * Get some random published quotes.
+     *
+     * @return \Illuminate\Support\Collection
+     */
     private function retrieveWeeklyQuotes()
     {
         return $this->quoteRepo->randomPublished($this->getNbQuotes());
     }
 
+    /**
+     * Get some quotes that were published today.
+     *
+     * @return \Illuminate\Support\Collection
+     */
     private function retrieveDailyQuotes()
     {
         return $this->quoteRepo->randomPublishedToday($this->getNbQuotes());
     }
 
+    /**
+     * Get the type given when the command was launched.
+     *
+     * @return string
+     */
     private function getType()
     {
         return $this->argument('type');
     }
 
+    /**
+     * Get the number of quotes to send.
+     *
+     * @return int
+     */
     private function getNbQuotes()
     {
         $type = $this->getType();

app/TeenQuotes/Newsletters/Controllers/MailchimpWebhook.php

@@ -14,20 +14,25 @@
 class MailchimpWebhook extends BaseController
 {
     /**
-     * @var \TeenQuotes\Newsletters\Repositories\NewsletterRepository
+     * @var NewsletterRepository
      */
     private $newsletterRepo;
 
     /**
-     * @var \TeenQuotes\Users\Repositories\UserRepository
+     * @var UserRepository
      */
     private $userRepo;
 
     /**
-     * @var \TeenQuotes\Newsletters\NewsletterList
+     * @var NewsletterList
      */
     private $newsletterList;
 
+    /**
+     * @param UserRepository       $userRepo
+     * @param NewsletterRepository $newsletterRepo
+     * @param NewsletterList       $newsletterList
+     */
     public function __construct(UserRepository $userRepo, NewsletterRepository $newsletterRepo,
                                 NewsletterList $newsletterList)
     {
@@ -36,6 +41,11 @@ public function __construct(UserRepository $userRepo, NewsletterRepository $news
         $this->newsletterList = $newsletterList;
     }
 
+    /**
+     * Listen for the incoming webhooks and handle them.
+     *
+     * @return Response
+     */
     public function listen()
     {
         $this->checkKey(Input::get('key'));
@@ -62,7 +72,12 @@ public function listen()
         return Response::make('DONE', 200);
     }
 
-    private function bounce($data)
+    /**
+     * Handle the bounce event.
+     *
+     * @param array $data
+     */
+    private function bounce(array $data)
     {
         $user = $this->userRepo->getByEmail($data['email']);
 
@@ -71,7 +86,12 @@ private function bounce($data)
         }
     }
 
-    private function unsubscribe($data)
+    /**
+     * Handle the unsubscribe event.
+     *
+     * @param array $data
+     */
+    private function unsubscribe(array $data)
     {
         $type = $this->getTypeFromListId($data['list_id']);
 
@@ -82,7 +102,12 @@ private function unsubscribe($data)
         }
     }
 
-    private function changeEmail($data)
+    /**
+     * Handle the event when an user has changed its email address.
+     *
+     * @param array $data
+     */
+    private function changeEmail(array $data)
     {
         $oldEmail = $data['old_email'];
         $newEmail = $data['new_email'];
@@ -94,11 +119,25 @@ private function changeEmail($data)
         }
     }
 
+    /**
+     * Get the type of a newsletter from its list ID.
+     *
+     * @param string $listId
+     *
+     * @return string
+     */
     private function getTypeFromListId($listId)
     {
         return str_replace('Newsletter', '', $this->newsletterList->getNameFromListId($listId));
     }
 
+    /**
+     * Check the given secret key.
+     *
+     * @param string $key
+     *
+     * @throws InvalidArgumentException The key was wrong
+     */
     private function checkKey($key)
     {
         if ($key != Config::get('services.mailchimp.secret')) {

app/TeenQuotes/Newsletters/Mailchimp/NewsletterList.php

@@ -40,6 +40,11 @@ class NewsletterList implements NewsletterListInterface
         'dailyNewsletter'  => 'f9e52170f4',
     ];
 
+    /**
+     * @param View           $view
+     * @param Config         $config
+     * @param UserRepository $userRepo
+     */
     public function __construct(View $view, Config $config, UserRepository $userRepo)
     {
         $this->mailchimp = App::make('MailchimpClient');
@@ -51,8 +56,8 @@ public function __construct(View $view, Config $config, UserRepository $userRepo
     /**
      * Subscribe a user to a Mailchimp list.
      *
-     * @param string                        $listName
-     * @param \TeenQuotes\Users\Models\User $email
+     * @param string $listName
+     * @param User   $email
      *
      * @return mixed
      */
@@ -92,8 +97,8 @@ public function subscribeUsersTo($listName, Collection $collection)
     /**
      * Unsubscribe a user from a Mailchimp list.
      *
-     * @param string                        $listName
-     * @param \TeenQuotes\Users\Models\User $email
+     * @param string $listName
+     * @param User   $email
      *
      * @return mixed
      */
@@ -167,7 +172,7 @@ public function sendCampaign($listName, $subject, $toName, $viewName, $viewData)
      *
      * @param string $listName
      *
-     * @return \Illuminate\Support\Collection $collection A collection of users
+     * @return Collection $collection A collection of users
      */
     public function getUnsubscribesFromList($listName)
     {

app/TeenQuotes/Newsletters/Models/Newsletter.php

@@ -18,11 +18,21 @@ class Newsletter extends Eloquent
 
     protected $fillable = [];
 
+    /**
+     * Tell if it's the daily newsletter.
+     *
+     * @return bool
+     */
     public function isDaily()
     {
         return ($this->type == self::DAILY);
     }
 
+    /**
+     * Tell if it's the weekly newsletter.
+     *
+     * @return bool
+     */
     public function isWeekly()
     {
         return ($this->type == self::WEEKLY);

app/TeenQuotes/Newsletters/NewslettersManager.php

@@ -11,21 +11,31 @@
 class NewslettersManager
 {
     /**
-     * @var \TeenQuotes\Newsletters\Repositories\NewsletterRepository
+     * @var NewsletterRepository
      */
     private $newslettersRepo;
 
     /**
-     * @var \TeenQuotes\Newsletters\NewsletterList
+     * @var NewsletterList
      */
     private $newslettersList;
 
+    /**
+     * @param NewsletterRepository $newslettersRepo
+     * @param NewsletterList       $newslettersList
+     */
     public function __construct(NewsletterRepository $newslettersRepo, NewsletterList $newslettersList)
     {
         $this->newslettersRepo = $newslettersRepo;
         $this->newslettersList = $newslettersList;
     }
 
+    /**
+     * Subscribe a user to a newsletter.
+     *
+     * @param User   $user
+     * @param string $type The newsletter's type
+     */
     public function createForUserAndType(User $user, $type)
     {
         $this->newslettersRepo->createForUserAndType($user, $type);
@@ -35,6 +45,12 @@ public function createForUserAndType(User $user, $type)
         }
     }
 
+    /**
+     * Unsubscribe a user from a newsletter.
+     *
+     * @param User   $u
+     * @param string $type The newsletter's type
+     */
     public function deleteForUserAndType(User $u, $type)
     {
         if ($this->shouldCallAPI()) {
@@ -44,6 +60,11 @@ public function deleteForUserAndType(User $u, $type)
         return $this->newslettersRepo->deleteForUserAndType($u, $type);
     }
 
+    /**
+     * Unsubscribe multiple users from all newsletters.
+     *
+     * @param Collection $users
+     */
     public function deleteForUsers(Collection $users)
     {
         if ($this->shouldCallAPI()) {
@@ -55,11 +76,23 @@ public function deleteForUsers(Collection $users)
         return $this->newslettersRepo->deleteForUsers($users);
     }
 
+    /**
+     * Determine if we should call the API.
+     *
+     * @return bool
+     */
     private function shouldCallAPI()
     {
         return App::environment() == 'production';
     }
 
+    /**
+     * Get the name of a newsletter's list for a given type.
+     *
+     * @param string $type
+     *
+     * @return string
+     */
     private function getListNameFromType($type)
     {
         return $type.'Newsletter';

app/TeenQuotes/Newsletters/Repositories/DbNewsletterRepository.php

@@ -12,8 +12,8 @@ class DbNewsletterRepository implements NewsletterRepository
     /**
      * Tells if a user if subscribed to a newsletter type.
      *
-     * @param \TeenQuotes\Users\Models\User $u    The given user
-     * @param string                        $type The newsletter's type
+     * @param User   $u    The given user
+     * @param string $type The newsletter's type
      *
      * @return bool
      *
@@ -33,7 +33,7 @@ public function userIsSubscribedToNewsletterType(User $u, $type)
      *
      * @param string $type
      *
-     * @return \Illuminate\Database\Eloquent\Collection
+     * @return Collection
      *
      * @see    \TeenQuotes\Newsletters\Models\Newsletter::getPossibleTypes()
      */
@@ -88,7 +88,7 @@ public function deleteForUserAndType(User $u, $type)
     /**
      * Delete all newsletters for a given user.
      *
-     * @param \TeenQuotes\Users\Models\User $u
+     * @param User $u
      *
      * @return int The number of affected rows
      */
@@ -100,7 +100,7 @@ public function deleteForUser(User $u)
     /**
      * Delete newsletters for a list of users.
      *
-     * @param \Illuminate\Support\Collection $users The collection of users
+     * @param Collection $users The collection of users
      *
      * @return int The number of affected rows
      */