From 16e7d6cff7800dd110e7cf47562683e6dc89e8f0 Mon Sep 17 00:00:00 2001 From: Eliseu Amaro Date: Wed, 26 Jan 2022 20:01:37 +0000 Subject: [PATCH] [COMPONENTS] Documenting methods with high cognitive complexity, specifically in Group and Posting components [PLUGINS][Directory] Updating docs, @params weren't set correctly --- components/Circle/Circle.php | 11 +++++++++++ components/Circle/Controller/Circle.php | 8 ++++++++ components/Group/Group.php | 17 +++++++++++++++-- components/Posting/Posting.php | 18 ++++++++++++++---- plugins/Directory/Directory.php | 7 +++++-- 5 files changed, 53 insertions(+), 8 deletions(-) diff --git a/components/Circle/Circle.php b/components/Circle/Circle.php index a76e2dfe0e..be44d87d76 100644 --- a/components/Circle/Circle.php +++ b/components/Circle/Circle.php @@ -195,6 +195,17 @@ class Circle extends Component return \in_array($vars['path'], ['actor_view_nickname', 'actor_view_id']); } + /** + * Retrieves an array of Collections owned by an Actor. + * In this case, Collections of those within Actor's own circle of Actors, aka ActorCircle. + * + * Differs from the overwritten method in MetaCollectionsTrait, since retrieved Collections come from the $owner + * itself, and from every Actor that is a part of its ActorCircle. + * + * @param Actor $owner the Actor, and by extension its own circle of Actors + * @param null|array $vars Page vars sent by AppendRightPanelBlock event + * @param bool $ids_only true if only the Collections ids are to be returned + */ protected function getCollectionsBy(Actor $owner, ?array $vars = null, bool $ids_only = false): array { $tagged_id = !\is_null($vars) ? $this->getActorIdFromVars($vars) : null; diff --git a/components/Circle/Controller/Circle.php b/components/Circle/Controller/Circle.php index 05d22b83b6..e4e4aa2fcb 100644 --- a/components/Circle/Controller/Circle.php +++ b/components/Circle/Controller/Circle.php @@ -31,6 +31,14 @@ use Component\Collection\Util\Controller\CircleController; class Circle extends CircleController { + /** + * Render an existing ActorCircle with the given id as a Collection of Actors + * + * @param ActorCircle|int $circle_id the desired ActorCircle id + * + * @throws \App\Util\Exception\ServerException + * @throws ClientException + */ public function circleById(int|ActorCircle $circle_id): array { $circle = \is_int($circle_id) ? ActorCircle::getByPK(['id' => $circle_id]) : $circle_id; diff --git a/components/Group/Group.php b/components/Group/Group.php index 93fd56cf22..0ee8c45b02 100644 --- a/components/Group/Group.php +++ b/components/Group/Group.php @@ -82,7 +82,9 @@ class Group extends Component if (str_starts_with($request->get('_route'), 'group_actor_view_')) { if (!\is_null($id = $request->get('id'))) { return Actor::getById((int) $id); - } elseif (!\is_null($nickname = $request->get('nickname'))) { + } + + if (!\is_null($nickname = $request->get('nickname'))) { return LocalGroup::getActorByNickname($nickname); } } @@ -99,7 +101,18 @@ class Group extends Component return Event::next; } - public function onPostingGetContextActor(Request $request, Actor $actor, ?Actor $context_actor) + /** + * Indicates the context in which Posting's form is to be presented. Passing on $context_actor to Posting's + * onAppendRightPostingBlock event, the Group a given $actor is currently browsing. + * + * Makes it possible to automagically fill in the targets (aka the Group which this $request route is connected to) + * in the Posting's form. + * + * @param null|Actor $context_actor Actor group, if current route is part of an existing Group set of routes + * + * @return bool + */ + public function onPostingGetContextActor(Request $request, Actor $actor, ?Actor &$context_actor) { $ctx = $this->getGroupFromContext($request); if (!\is_null($ctx)) { diff --git a/components/Posting/Posting.php b/components/Posting/Posting.php index 9ea00594ac..cc89d51d2e 100644 --- a/components/Posting/Posting.php +++ b/components/Posting/Posting.php @@ -64,7 +64,9 @@ class Posting extends Component * HTML render event handler responsible for adding and handling * the result of adding the note submission form, only if a user is logged in * + * @throws BugFoundException * @throws ClientException + * @throws DuplicateFoundException * @throws RedirectException * @throws ServerException */ @@ -191,11 +193,19 @@ class Posting extends Component * $actor_id, possibly as a reply to note $reply_to and with flag * $is_local. Sanitizes $content and $attachments * - * @param array $attachments Array of UploadedFile to be stored as GSFiles associated to this note - * @param array $processed_attachments Array of [Attachment, Attachment's name] to be associated to this $actor and Note - * @param array $process_note_content_extra_args Extra arguments for the event ProcessNoteContent + * @param Actor $actor The Actor responsible for the creation of this Note + * @param null|string $content The raw text content sent via Posting form + * @param string $content_type Indicating one of the various supported text format (Plain Text, Markdown, LaTeX...) + * @param null|string $locale Note's written text language, set by the default Actor language or upon filling Posting's form + * @param null|VisibilityScope $scope The scope of this Note + * @param null|Actor|int $target Filled by PostingFillTargetChoices, representing an Actor in its many forms to be targeted by this Note + * @param null|int $reply_to_id The soon-to-be Note parent's id, if it's a Reply itself + * @param array $attachments Array of UploadedFile to be stored as GSFiles associated to this note + * @param array $processed_attachments Array of [Attachment, Attachment's name] to be associated to this $actor and Note + * @param array $process_note_content_extra_args Extra arguments for the event ProcessNoteContent + * @param bool $notify True if the newly created Note activity should be passed on as a Notification + * @param null|string $rendered The Note's content post RenderNoteContent event, which sanitizes and processes the raw content sent * - * @throws BugFoundException * @throws ClientException * @throws DuplicateFoundException * @throws ServerException diff --git a/plugins/Directory/Directory.php b/plugins/Directory/Directory.php index 62dbd13299..539875506f 100644 --- a/plugins/Directory/Directory.php +++ b/plugins/Directory/Directory.php @@ -38,6 +38,8 @@ class Directory extends Plugin { /** * Map URLs to Controllers + * @param RouteLoader $r + * @return bool */ public function onAddRoute(RouteLoader $r) { @@ -50,6 +52,7 @@ class Directory extends Plugin /** * Add Links to menu * + * @param array $vars * @param array $res out menu items * * @return bool hook value; true means continue processing, false means stop @@ -64,12 +67,12 @@ class Directory extends Plugin /** * Prepend various widgets to Actors Collection template * + * @param Request $request * @param $elements array of widgets to be prepended * + * @return bool EventHook * @throws RedirectException * @throws ServerException - * - * @return bool EventHook */ public function onPrependActorsCollection(Request $request, array &$elements): bool {