Improve Following class documentation and method efficiency (#2086)

Author: obenland

.github/changelog/2086-from-description

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Improve Following class documentation and optimize count methods for better performance

includes/collection/class-followers.php

@@ -232,7 +232,7 @@ public static function get_followers_with_count( $user_id, $number = -1, $page =
 	 * @return int The number of Followers
 	 */
 	public static function count_followers( $user_id ) {
-		return self::get_followers_with_count( $user_id )['total'];
+		return self::get_followers_with_count( $user_id, 1 )['total'];
 	}
 
 	/**

includes/collection/class-following.php

@@ -8,7 +8,6 @@
 namespace Activitypub\Collection;
 
 use Activitypub\Activity\Activity;
-use Activitypub\Http;
 
 use function Activitypub\add_to_outbox;
 
@@ -54,14 +53,14 @@ class Following {
 	/**
 	 * Follow a user.
 	 *
-	 * Please do not use this method directly, use `Activitypub\follow` instead.
+	 * Please do not use this method directly, use `\Activitypub\follow` instead.
 	 *
-	 * @see Activitypub\follow
+	 * @see \Activitypub\follow
 	 *
 	 * @param \WP_Post|int $post    The ID of the remote Actor.
 	 * @param int          $user_id The ID of the WordPress User.
 	 *
-	 * @return \WP_Post|\WP_Error The ID of the Actor or a WP_Error.
+	 * @return int|false|\WP_Post|\WP_Error The Outbox ID or false on failure, the Actor post or a WP_Error.
 	 */
 	public static function follow( $post, $user_id ) {
 		$post = \get_post( $post );
@@ -146,9 +145,9 @@ public static function reject( $post, $user_id ) {
 	/**
 	 * Remove a follow request.
 	 *
-	 * Please do not use this method directly, use `Activitypub\unfollow` instead.
+	 * Please do not use this method directly, use `\Activitypub\unfollow` instead.
 	 *
-	 * @see Activitypub\unfollow
+	 * @see \Activitypub\unfollow
 	 *
 	 * @param \WP_Post|int $post    The ID of the remote Actor.
 	 * @param int          $user_id The ID of the WordPress User.
@@ -264,7 +263,7 @@ public static function get_following( $user_id, $number = -1, $page = null, $arg
 	 * @return int The total number of followings.
 	 */
 	public static function count_following( $user_id ) {
-		return self::get_following_with_count( $user_id, -1, null, array() )['total'];
+		return self::get_following_with_count( $user_id, 1 )['total'];
 	}
 
 	/**
@@ -330,7 +329,7 @@ public static function get_pending( $user_id, $number = -1, $page = null, $args
 	 * @return int The total number of pending followings.
 	 */
 	public static function count_pending( $user_id ) {
-		return self::get_pending_with_count( $user_id, -1, null, array() )['total'];
+		return self::get_pending_with_count( $user_id, 1 )['total'];
 	}
 
 	/**
@@ -341,7 +340,12 @@ public static function count_pending( $user_id ) {
 	 * @param int      $page    Page number.
 	 * @param array    $args    The WP_Query arguments.
 	 *
-	 * @return \WP_Post[] List of `Following` objects.
+	 * @return array {
+	 *      Data about the followings.
+	 *
+	 *      @type \WP_Post[] $followers List of `Follower` objects.
+	 *      @type int $total Total number of followers.
+	 * }
 	 */
 	public static function get_all_with_count( $user_id, $number = -1, $page = null, $args = array() ) {
 		$defaults = array(
@@ -380,7 +384,7 @@ public static function get_all_with_count( $user_id, $number = -1, $page = null,
 	 * @return \WP_Post[] List of `Following` objects.
 	 */
 	public static function get_all( $user_id ) {
-		return self::get_all_with_count( $user_id, -1, null, array() )['following'];
+		return self::get_all_with_count( $user_id )['following'];
 	}
 
 	/**
@@ -391,7 +395,7 @@ public static function get_all( $user_id ) {
 	 * @return int The total number of all followings.
 	 */
 	public static function count_all( $user_id ) {
-		return self::get_all_with_count( $user_id, -1, null, array() )['total'];
+		return self::get_all_with_count( $user_id, 1 )['total'];
 	}
 
 	/**
@@ -403,9 +407,9 @@ public static function count_all( $user_id ) {
 	 */
 	public static function count( $user_id ) {
 		return array(
-			self::ALL      => self::get_all_with_count( $user_id, -1, null, array() )['total'],
-			self::ACCEPTED => self::get_following_with_count( $user_id, -1, null, array() )['total'],
-			self::PENDING  => self::get_pending_with_count( $user_id, -1, null, array() )['total'],
+			self::ALL      => self::get_all_with_count( $user_id, 1 )['total'],
+			self::ACCEPTED => self::get_following_with_count( $user_id, 1 )['total'],
+			self::PENDING  => self::get_pending_with_count( $user_id, 1 )['total'],
 		);
 	}
 

includes/functions.php

@@ -1551,7 +1551,7 @@ function add_to_outbox( $data, $activity_type = null, $user_id = 0, $content_vis
  * @param string|int $remote_actor The Actor URL, WebFinger Resource or Post-ID of the remote Actor.
  * @param int        $user_id      The ID of the WordPress User.
  *
- * @return \WP_Post|\WP_Error The ID of the Outbox item or a WP_Error.
+ * @return int|false|\WP_Post|\WP_Error The Outbox ID or false on failure, the Actor post or a WP_Error.
  */
 function follow( $remote_actor, $user_id ) {
 	if ( \is_numeric( $remote_actor ) ) {
@@ -1581,7 +1581,7 @@ function follow( $remote_actor, $user_id ) {
  * @param string|int $remote_actor The Actor URL, WebFinger Resource or Post-ID of the remote Actor.
  * @param int        $user_id      The ID of the WordPress User.
  *
- * @return \WP_Post|\WP_Error The ID of the Outbox item or a WP_Error.
+ * @return \WP_Post|\WP_Error The Actor post or a WP_Error.
  */
 function unfollow( $remote_actor, $user_id ) {
 	if ( \is_numeric( $remote_actor ) ) {