From c3d58c350e78b27fcb24f79ede70bb5f99c305c5 Mon Sep 17 00:00:00 2001
From: Phablulo <phablulo@gmail.com>
Date: Fri, 7 Jan 2022 09:23:37 -0300
Subject: [PATCH] [COMPONENTS][Collections] Iterating documentation

---
 components/Circle/Circle.php                  |  4 +-
 .../Collection/Util/MetaCollectionTrait.php   | 38 +++++++++++++++++--
 .../AttachmentCollections.php                 |  4 +-
 3 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/components/Circle/Circle.php b/components/Circle/Circle.php
index fda3713b38..2aa2f08dce 100644
--- a/components/Circle/Circle.php
+++ b/components/Circle/Circle.php
@@ -157,7 +157,7 @@ class Circle extends Component
         ]));
     }
 
-    protected function removeItems(Actor $owner, array $vars, $items, array $collections)
+    protected function removeItem(Actor $owner, array $vars, $items, array $collections)
     {
         $tagger_id                     = $owner->getId();
         $tagged_id                     = $this->getActorIdFromVars($vars);
@@ -172,7 +172,7 @@ class Circle extends Component
         Cache::delete(Actor::cacheKeys($tagger_id)['circles']);
     }
 
-    protected function addItems(Actor $owner, array $vars, $items, array $collections)
+    protected function addItem(Actor $owner, array $vars, $items, array $collections)
     {
         $tagger_id                = $owner->getId();
         $tagged_id                = $this->getActorIdFromVars($vars);
diff --git a/components/Collection/Util/MetaCollectionTrait.php b/components/Collection/Util/MetaCollectionTrait.php
index 9563dec731..3ac6f4247e 100644
--- a/components/Collection/Util/MetaCollectionTrait.php
+++ b/components/Collection/Util/MetaCollectionTrait.php
@@ -49,14 +49,44 @@ trait MetaCollectionTrait
     //protected string $slug        = 'collection';
     //protected string $plural_slug = 'collections';
 
+    /**
+     * create a collection owned by Actor $owner.
+     *
+     * @param Actor  $owner The collection's owner
+     * @param array  $vars  Page vars sent by AppendRightPanelBlock event
+     * @param string $name  Collection's name
+     */
     abstract protected function createCollection(Actor $owner, array $vars, string $name);
-    abstract protected function removeItems(Actor $owner, array $vars, $items, array $collections);
-    abstract protected function addItems(Actor $owner, array $vars, $items, array $collections);
+    /**
+     * remove item from collections.
+     *
+     * @param Actor $owner       Current user
+     * @param array $vars        Page vars sent by AppendRightPanelBlock event
+     * @param array $items       Array of collections's ids to remove the current item from
+     * @param array $collections List of ids of collections owned by $owner
+     */
+    abstract protected function removeItem(Actor $owner, array $vars, array $items, array $collections);
+    /**
+     * add item to collections.
+     *
+     * @param Actor $owner       Current user
+     * @param array $vars        Page vars sent by AppendRightPanelBlock event
+     * @param array $items       Array of collections's ids to add the current item to
+     * @param array $collections List of ids of collections owned by $owner
+     */
+    abstract protected function addItem(Actor $owner, array $vars, array $items, array $collections);
 
     /**
      * Check the route to determine whether the widget should be added
      */
     abstract protected function shouldAddToRightPanel(Actor $user, $vars, Request $request): bool;
+    /**
+     * Get array of collections's owned by $actor
+     *
+     * @param Actor  $owner    Collection's owner
+     * @param ?array $vars     Page vars sent by AppendRightPanelBlock event
+     * @param bool   $ids_only if true, the function must return only the primary key or each collections
+     */
     abstract protected function getCollectionsBy(Actor $owner, ?array $vars = null, bool $ids_only = false): array;
 
     /**
@@ -109,10 +139,10 @@ trait MetaCollectionTrait
             $removed  = array_filter($already_selected, fn ($x) => !\in_array($x, $selected));
             $added    = array_filter($selected, fn ($x) => !\in_array($x, $already_selected));
             if (\count($removed) > 0) {
-                $this->removeItems($user, $vars, $removed, $collections);
+                $this->removeItem($user, $vars, $removed, $collections);
             }
             if (\count($added) > 0) {
-                $this->addItems($user, $vars, $added, $collections);
+                $this->addItem($user, $vars, $added, $collections);
             }
             DB::flush();
             throw new RedirectException();
diff --git a/plugins/AttachmentCollections/AttachmentCollections.php b/plugins/AttachmentCollections/AttachmentCollections.php
index 05e6394559..484ed90177 100644
--- a/plugins/AttachmentCollections/AttachmentCollections.php
+++ b/plugins/AttachmentCollections/AttachmentCollections.php
@@ -65,7 +65,7 @@ class AttachmentCollections extends Plugin
             'collection_id' => $col->getId(),
         ]));
     }
-    protected function removeItems(Actor $owner, array $vars, $items, array $collections)
+    protected function removeItem(Actor $owner, array $vars, array $items, array $collections)
     {
         return DB::dql(<<<'EOF'
             DELETE FROM \Plugin\AttachmentCollections\Entity\AttachmentCollectionEntry AS entry
@@ -83,7 +83,7 @@ class AttachmentCollections extends Plugin
         ]);
     }
 
-    protected function addItems(Actor $owner, array $vars, $items, array $collections)
+    protected function addItem(Actor $owner, array $vars, array $items, array $collections)
     {
         foreach ($items as $id) {
             // prevent user from putting something in a collection (s)he doesn't own: