[COMPONENTS] Documenting methods with high cognitive complexity, specifically in Group and Posting components

[PLUGINS][Directory] Updating docs, @params weren't set correctly
This commit is contained in:
Eliseu Amaro 2022-01-26 20:01:37 +00:00
parent 6a5312aca9
commit 16e7d6cff7
No known key found for this signature in database
GPG Key ID: 96DA09D4B97BC2D5
5 changed files with 53 additions and 8 deletions

View File

@ -195,6 +195,17 @@ class Circle extends Component
return \in_array($vars['path'], ['actor_view_nickname', 'actor_view_id']); 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 protected function getCollectionsBy(Actor $owner, ?array $vars = null, bool $ids_only = false): array
{ {
$tagged_id = !\is_null($vars) ? $this->getActorIdFromVars($vars) : null; $tagged_id = !\is_null($vars) ? $this->getActorIdFromVars($vars) : null;

View File

@ -31,6 +31,14 @@ use Component\Collection\Util\Controller\CircleController;
class Circle extends 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 public function circleById(int|ActorCircle $circle_id): array
{ {
$circle = \is_int($circle_id) ? ActorCircle::getByPK(['id' => $circle_id]) : $circle_id; $circle = \is_int($circle_id) ? ActorCircle::getByPK(['id' => $circle_id]) : $circle_id;

View File

@ -82,7 +82,9 @@ class Group extends Component
if (str_starts_with($request->get('_route'), 'group_actor_view_')) { if (str_starts_with($request->get('_route'), 'group_actor_view_')) {
if (!\is_null($id = $request->get('id'))) { if (!\is_null($id = $request->get('id'))) {
return Actor::getById((int) $id); return Actor::getById((int) $id);
} elseif (!\is_null($nickname = $request->get('nickname'))) { }
if (!\is_null($nickname = $request->get('nickname'))) {
return LocalGroup::getActorByNickname($nickname); return LocalGroup::getActorByNickname($nickname);
} }
} }
@ -99,7 +101,18 @@ class Group extends Component
return Event::next; 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); $ctx = $this->getGroupFromContext($request);
if (!\is_null($ctx)) { if (!\is_null($ctx)) {

View File

@ -64,7 +64,9 @@ class Posting extends Component
* HTML render event handler responsible for adding and handling * HTML render event handler responsible for adding and handling
* the result of adding the note submission form, only if a user is logged in * the result of adding the note submission form, only if a user is logged in
* *
* @throws BugFoundException
* @throws ClientException * @throws ClientException
* @throws DuplicateFoundException
* @throws RedirectException * @throws RedirectException
* @throws ServerException * @throws ServerException
*/ */
@ -191,11 +193,19 @@ class Posting extends Component
* $actor_id, possibly as a reply to note $reply_to and with flag * $actor_id, possibly as a reply to note $reply_to and with flag
* $is_local. Sanitizes $content and $attachments * $is_local. Sanitizes $content and $attachments
* *
* @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 $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 $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 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 ClientException
* @throws DuplicateFoundException * @throws DuplicateFoundException
* @throws ServerException * @throws ServerException

View File

@ -38,6 +38,8 @@ class Directory extends Plugin
{ {
/** /**
* Map URLs to Controllers * Map URLs to Controllers
* @param RouteLoader $r
* @return bool
*/ */
public function onAddRoute(RouteLoader $r) public function onAddRoute(RouteLoader $r)
{ {
@ -50,6 +52,7 @@ class Directory extends Plugin
/** /**
* Add Links to menu * Add Links to menu
* *
* @param array $vars
* @param array $res out menu items * @param array $res out menu items
* *
* @return bool hook value; true means continue processing, false means stop * @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 * Prepend various widgets to Actors Collection template
* *
* @param Request $request
* @param $elements array of widgets to be prepended * @param $elements array of widgets to be prepended
* *
* @return bool EventHook
* @throws RedirectException * @throws RedirectException
* @throws ServerException * @throws ServerException
*
* @return bool EventHook
*/ */
public function onPrependActorsCollection(Request $request, array &$elements): bool public function onPrependActorsCollection(Request $request, array &$elements): bool
{ {