From 154b0018afd2b4407c692379c75e3e4b188d487f Mon Sep 17 00:00:00 2001
From: Matthias Pfefferle <pfefferle@users.noreply.github.com>
Date: Wed, 10 May 2023 15:36:45 +0200
Subject: [PATCH] PHPDoc

---
 includes/class-activity-dispatcher.php | 16 ++---
 includes/debug.php                     |  3 +-
 includes/functions.php                 | 40 ++++++------
 includes/model/class-activity.php      | 85 +++++++++++++++++++++++++-
 4 files changed, 113 insertions(+), 31 deletions(-)

diff --git a/includes/class-activity-dispatcher.php b/includes/class-activity-dispatcher.php
index 422240d..ee435a7 100644
--- a/includes/class-activity-dispatcher.php
+++ b/includes/class-activity-dispatcher.php
@@ -5,6 +5,8 @@ use Activitypub\Model\Post;
 use Activitypub\Model\Activity;
 use Activitypub\Collection\Followers;
 
+use function Activitypub\safe_remote_post;
+
 /**
  * ActivityPub Activity_Dispatcher Class
  *
@@ -37,7 +39,7 @@ class Activity_Dispatcher {
 	/**
 	 * Send "update" activities.
 	 *
-	 * @param Activitypub\Model\Post $activitypub_post
+	 * @param Activitypub\Model\Post $activitypub_post The ActivityPub Post.
 	 */
 	public static function send_update_activity( Post $activitypub_post ) {
 		self::send_activity( $activitypub_post, 'Update' );
@@ -46,23 +48,23 @@ class Activity_Dispatcher {
 	/**
 	 * Send "delete" activities.
 	 *
-	 * @param Activitypub\Model\Post $activitypub_post
+	 * @param Activitypub\Model\Post $activitypub_post The ActivityPub Post.
 	 */
 	public static function send_delete_activity( Post $activitypub_post ) {
 		self::send_activity( $activitypub_post, 'Delete' );
 	}
 
 	/**
-	 * Undocumented function
+	 * Send Activities to followers and mentioned users.
 	 *
-	 * @param Activitypub\Model\Post $activitypub_post
-	 * @param [type] $activity_type
+	 * @param Activitypub\Model\Post $activitypub_post The ActivityPub Post.
+	 * @param string                 $activity_type    The Activity-Type.
 	 *
 	 * @return void
 	 */
 	public static function send_activity( Post $activitypub_post, $activity_type ) {
 		// check if a migration is needed before sending new posts
-		\Activitypub\Migration::maybe_migrate();
+		Migration::maybe_migrate();
 
 		// get latest version of post
 		$user_id = $activitypub_post->get_post_author();
@@ -79,7 +81,7 @@ class Activity_Dispatcher {
 		foreach ( $inboxes as $inbox ) {
 			$activity = $activitypub_activity->to_json();
 
-			\Activitypub\safe_remote_post( $inbox, $activity, $user_id );
+			safe_remote_post( $inbox, $activity, $user_id );
 		}
 	}
 }
diff --git a/includes/debug.php b/includes/debug.php
index a5683f4..d42b2a9 100644
--- a/includes/debug.php
+++ b/includes/debug.php
@@ -6,7 +6,8 @@ namespace Activitypub;
  *
  * @param array  $r   Array of HTTP request args.
  * @param string $url The request URL.
- * @return array $args Array or string of HTTP request arguments.
+ *
+ * @return array Array or string of HTTP request arguments.
  */
 function allow_localhost( $r, $url ) {
 	$r['reject_unsafe_urls'] = false;
diff --git a/includes/functions.php b/includes/functions.php
index bd04e6c..19a3512 100644
--- a/includes/functions.php
+++ b/includes/functions.php
@@ -43,9 +43,9 @@ function safe_remote_get( $url, $user_id ) {
 /**
  * Returns a users WebFinger "resource"
  *
- * @param int $user_id
+ * @param int $user_id The User-ID.
  *
- * @return string The user-resource
+ * @return string The User-Resource.
  */
 function get_webfinger_resource( $user_id ) {
 	return Webfinger::get_user_resource( $user_id );
@@ -123,29 +123,24 @@ function get_remote_metadata_by_actor( $actor ) {
 	return $metadata;
 }
 
-function get_identifier_settings( $user_id ) {
-	?>
-<table class="form-table">
-	<tbody>
-		<tr>
-			<th scope="row">
-				<label><?php \esc_html_e( 'Profile identifier', 'activitypub' ); ?></label>
-			</th>
-			<td>
-				<p><code><?php echo \esc_html( \Activitypub\get_webfinger_resource( $user_id ) ); ?></code> or <code><?php echo \esc_url( \get_author_posts_url( $user_id ) ); ?></code></p>
-				<?php // translators: the webfinger resource ?>
-				<p class="description"><?php \printf( \esc_html__( 'Try to follow "@%s" by searching for it on Mastodon,Friendica & Co.', 'activitypub' ), \esc_html( \Activitypub\get_webfinger_resource( $user_id ) ) ); ?></p>
-			</td>
-		</tr>
-	</tbody>
-</table>
-	<?php
-}
-
+/**
+ * Returns the followers of a given user.
+ *
+ * @param int $user_id The User-ID.
+ *
+ * @return array The followers.
+ */
 function get_followers( $user_id ) {
 	return Collection\Followers::get_followers( $user_id );
 }
 
+/**
+ * Count the number of followers for a given user.
+ *
+ * @param int $user_id The User-ID.
+ *
+ * @return int The number of followers.
+ */
 function count_followers( $user_id ) {
 	return Collection\Followers::count_followers( $user_id );
 }
@@ -202,7 +197,8 @@ function url_to_authorid( $url ) {
  * Return the custom Activity Pub description, if set, or default author description.
  *
  * @param int $user_id The user ID.
- * @return string
+ *
+ * @return string The author description.
  */
 function get_author_description( $user_id ) {
 	$description = get_user_meta( $user_id, 'activitypub_user_description', true );
diff --git a/includes/model/class-activity.php b/includes/model/class-activity.php
index 34f6146..b5372dc 100644
--- a/includes/model/class-activity.php
+++ b/includes/model/class-activity.php
@@ -9,6 +9,11 @@ namespace Activitypub\Model;
  * @see https://www.w3.org/TR/activitypub/
  */
 class Activity {
+	/**
+	 * The JSON-LD context.
+	 *
+	 * @var array
+	 */
 	private $context = array(
 		'https://www.w3.org/ns/activitystreams',
 		'https://w3id.org/security/v1',
@@ -30,14 +35,62 @@ class Activity {
 			),
 		),
 	);
+
+	/**
+	 * The published date.
+	 *
+	 * @var string
+	 */
 	private $published = '';
+
+	/**
+	 * The Activity-ID.
+	 *
+	 * @var string
+	 */
 	private $id = '';
+
+	/**
+	 * The Activity-Type.
+	 *
+	 * @var string
+	 */
 	private $type = 'Create';
+
+	/**
+	 * The Activity-Actor.
+	 *
+	 * @var string
+	 */
 	private $actor = '';
+
+	/**
+	 * The Audience.
+	 *
+	 * @var array
+	 */
 	private $to = array( 'https://www.w3.org/ns/activitystreams#Public' );
+
+	/**
+	 * The CC.
+	 *
+	 * @var array
+	 */
 	private $cc = array();
+
+	/**
+	 * The Activity-Object.
+	 *
+	 * @var array
+	 */
 	private $object = null;
 
+	/**
+	 * The Class-Constructor.
+	 *
+	 * @param string  $type    The Activity-Type.
+	 * @param boolean $context The JSON-LD context.
+	 */
 	public function __construct( $type = 'Create', $context = true ) {
 		if ( true !== $context ) {
 			$this->context = null;
@@ -47,6 +100,14 @@ class Activity {
 		$this->published = \gmdate( 'Y-m-d\TH:i:s\Z', \strtotime( 'now' ) );
 	}
 
+	/**
+	 * Magic Getter/Setter
+	 *
+	 * @param string $method The method name.
+	 * @param string $params The method params.
+	 *
+	 * @return mixed The value.
+	 */
 	public function __call( $method, $params ) {
 		$var = \strtolower( \substr( $method, 4 ) );
 
@@ -73,6 +134,13 @@ class Activity {
 		}
 	}
 
+	/**
+	 * Convert from a Post-Object.
+	 *
+	 * @param Post $post The Post-Object.
+	 *
+	 * @return void
+	 */
 	public function from_post( Post $post ) {
 		$this->object = $post->to_array();
 
@@ -111,6 +179,11 @@ class Activity {
 
 	}
 
+	/**
+	 * Convert to an Array.
+	 *
+	 * @return array The Array.
+	 */
 	public function to_array() {
 		$array = array_filter( \get_object_vars( $this ) );
 
@@ -126,12 +199,17 @@ class Activity {
 	/**
 	 * Convert to JSON
 	 *
-	 * @return void
+	 * @return string The JSON.
 	 */
 	public function to_json() {
 		return \wp_json_encode( $this->to_array(), \JSON_HEX_TAG | \JSON_HEX_AMP | \JSON_HEX_QUOT );
 	}
 
+	/**
+	 * Convert to a Simple Array.
+	 *
+	 * @return string The array.
+	 */
 	public function to_simple_array() {
 		$activity = array(
 			'@context' => $this->context,
@@ -149,6 +227,11 @@ class Activity {
 		return $activity;
 	}
 
+	/**
+	 * Convert to a Simple JSON.
+	 *
+	 * @return string The JSON.
+	 */
 	public function to_simple_json() {
 		return \wp_json_encode( $this->to_simple_array(), \JSON_HEX_TAG | \JSON_HEX_AMP | \JSON_HEX_QUOT );
 	}