PHPCS: Enable Commenting sniff (#925)

* PHPCS: Enable Commenting sniff

* Apply suggestions from code review

Co-authored-by: Matthias Pfefferle <pfefferle@users.noreply.github.com>

* Fix param alignment.

---------

Co-authored-by: Matthias Pfefferle <pfefferle@users.noreply.github.com>

Author: obenland

activitypub.php

@@ -11,15 +11,14 @@
  * Requires PHP: 7.0
  * Text Domain: activitypub
  * Domain Path: /languages
+ *
+ * @package Activitypub
  */
 
 namespace Activitypub;
 
 use WP_CLI;
 
-use function Activitypub\is_blog_public;
-use function Activitypub\site_supports_blocks;
-
 require_once __DIR__ . '/includes/compat.php';
 require_once __DIR__ . '/includes/functions.php';
 
@@ -39,7 +38,7 @@
 \defined( 'ACTIVITYPUB_AUTHORIZED_FETCH' ) || \define( 'ACTIVITYPUB_AUTHORIZED_FETCH', false );
 \defined( 'ACTIVITYPUB_DISABLE_REWRITES' ) || \define( 'ACTIVITYPUB_DISABLE_REWRITES', false );
 \defined( 'ACTIVITYPUB_DISABLE_INCOMING_INTERACTIONS' ) || \define( 'ACTIVITYPUB_DISABLE_INCOMING_INTERACTIONS', false );
-// Disable reactions like `Like` and `Announce` by default
+// Disable reactions like `Like` and `Announce` by default.
 \defined( 'ACTIVITYPUB_DISABLE_REACTIONS' ) || \define( 'ACTIVITYPUB_DISABLE_REACTIONS', true );
 \defined( 'ACTIVITYPUB_DISABLE_OUTGOING_INTERACTIONS' ) || \define( 'ACTIVITYPUB_DISABLE_OUTGOING_INTERACTIONS', false );
 \defined( 'ACTIVITYPUB_SHARED_INBOX_FEATURE' ) || \define( 'ACTIVITYPUB_SHARED_INBOX_FEATURE', false );
@@ -66,7 +65,7 @@ function rest_init() {
 	Rest\Collection::init();
 	Rest\Interaction::init();
 
-	// load NodeInfo endpoints only if blog is public
+	// Load NodeInfo endpoints only if blog is public.
 	if ( is_blog_public() ) {
 		Rest\NodeInfo::init();
 	}
@@ -103,7 +102,7 @@ function plugin_init() {
 
 
 /**
- * Class Autoloader
+ * Class Autoloader.
  */
 \spl_autoload_register(
 	function ( $full_class ) {
@@ -131,7 +130,7 @@ function ( $full_class ) {
 			if ( file_exists( $file ) && is_readable( $file ) ) {
 				require_once $file;
 			} else {
-				// translators: %s is the class name
+				// translators: %s is the class name.
 				$message = sprintf( esc_html__( 'Required class not found or not readable: %s', 'activitypub' ), esc_html( $full_class ) );
 				Debug::write_log( $message );
 				\wp_die( $message ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
@@ -141,7 +140,9 @@ function ( $full_class ) {
 );
 
 /**
- * Add plugin settings link
+ * Add plugin settings link.
+ *
+ * @param array $actions The current actions.
  */
 function plugin_settings_link( $actions ) {
 	$settings_link   = array();
@@ -179,13 +180,14 @@ function plugin_settings_link( $actions ) {
 	)
 );
 
-// Load integrations
+// Load integrations.
 require_once __DIR__ . '/integration/load.php';
 
 /**
- * `get_plugin_data` wrapper
+ * `get_plugin_data` wrapper.
  *
- * @return array The plugin metadata array
+ * @param array $default_headers Optional. The default plugin headers. Default empty array.
+ * @return array The plugin metadata array.
  */
 function get_plugin_meta( $default_headers = array() ) {
 	if ( ! $default_headers ) {
@@ -221,7 +223,7 @@ function get_plugin_version() {
 	return $meta['Version'];
 }
 
-// Check for CLI env, to add the CLI commands
+// Check for CLI env, to add the CLI commands.
 if ( defined( 'WP_CLI' ) && WP_CLI ) {
 	WP_CLI::add_command(
 		'activitypub',

includes/activity/class-activity.php

@@ -3,11 +3,13 @@
  * Inspired by the PHP ActivityPub Library by @Landrok
  *
  * @link https://github.com/landrok/activitypub
+ *
+ * @package Activitypub
  */
 
 namespace Activitypub\Activity;
 
-use Activitypub\Activity\Base_Object;
+use Activitypub\Link;
 
 /**
  * \Activitypub\Activity\Activity implements the common
@@ -150,12 +152,12 @@ class Activity extends Base_Object {
 	 * @return void
 	 */
 	public function set_object( $data ) {
-		// convert array to object
+		// Convert array to object.
 		if ( is_array( $data ) ) {
 			$data = self::init_from_array( $data );
 		}
 
-		// set object
+		// Set object.
 		$this->set( 'object', $data );
 
 		if ( ! is_object( $data ) ) {
@@ -202,7 +204,7 @@ public function get_json_ld_context() {
 		if ( $this->object instanceof Base_Object ) {
 			$class = get_class( $this->object );
 			if ( $class && $class::JSON_LD_CONTEXT ) {
-				// Without php 5.6 support this could be just: 'return  $this->object::JSON_LD_CONTEXT;'
+				// Without php 5.6 support this could be just: 'return  $this->object::JSON_LD_CONTEXT;'.
 				return $class::JSON_LD_CONTEXT;
 			}
 		}

includes/activity/class-actor.php

@@ -3,6 +3,8 @@
  * Inspired by the PHP ActivityPub Library by @Landrok
  *
  * @link https://github.com/landrok/activitypub
+ *
+ * @package Activitypub
  */
 
 namespace Activitypub\Activity;

includes/activity/class-base-object.php

@@ -3,6 +3,8 @@
  * Inspired by the PHP ActivityPub Library by @Landrok
  *
  * @link https://github.com/landrok/activitypub
+ *
+ * @package Activitypub
  */
 
 namespace Activitypub\Activity;
@@ -431,7 +433,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitypub/#source-property
 	 *
-	 * @var ObjectType
+	 * @var array
 	 */
 	protected $source;
 
@@ -460,12 +462,10 @@ class Base_Object {
 	protected $sensitive = false;
 
 	/**
-	 * Magic function to implement getter and setter
+	 * Magic function to implement getter and setter.
 	 *
 	 * @param string $method The method name.
 	 * @param string $params The method params.
-	 *
-	 * @return void
 	 */
 	public function __call( $method, $params ) {
 		$var = \strtolower( \substr( $method, 4 ) );
@@ -577,9 +577,9 @@ public function add( $key, $value ) {
 	/**
 	 * Convert JSON input to an array.
 	 *
-	 * @return string The JSON string.
+	 * @param string $json The JSON string.
 	 *
-	 * @return \Activitypub\Activity\Base_Object An Object built from the JSON string.
+	 * @return Base_Object An Object built from the JSON string.
 	 */
 	public static function init_from_json( $json ) {
 		$array = \json_decode( $json, true );
@@ -653,12 +653,12 @@ public function to_array( $include_json_ld_context = true ) {
 		$vars  = get_object_vars( $this );
 
 		foreach ( $vars as $key => $value ) {
-			// ignotre all _prefixed keys.
+			// Ignore all _prefixed keys.
 			if ( '_' === substr( $key, 0, 1 ) ) {
 				continue;
 			}
 
-			// if value is empty, try to get it from a getter.
+			// If value is empty, try to get it from a getter.
 			if ( ! $value ) {
 				$value = call_user_func( array( $this, 'get_' . $key ) );
 			}
@@ -667,7 +667,7 @@ public function to_array( $include_json_ld_context = true ) {
 				$value = $value->to_array( false );
 			}
 
-			// if value is still empty, ignore it for the array and continue.
+			// If value is still empty, ignore it for the array and continue.
 			if ( isset( $value ) ) {
 				$array[ snake_to_camel_case( $key ) ] = $value;
 			}
@@ -681,10 +681,28 @@ public function to_array( $include_json_ld_context = true ) {
 		$class = new ReflectionClass( $this );
 		$class = strtolower( $class->getShortName() );
 
+		/**
+		 * Filter the array of the ActivityPub object.
+		 *
+		 * @param array       $array  The array of the ActivityPub object.
+		 * @param string      $class  The class of the ActivityPub object.
+		 * @param int         $id     The ID of the ActivityPub object.
+		 * @param Base_Object $object The ActivityPub object.
+		 *
+		 * @return array The filtered array of the ActivityPub object.
+		 */
 		$array = \apply_filters( 'activitypub_activity_object_array', $array, $class, $this->id, $this );
-		$array = \apply_filters( "activitypub_activity_{$class}_object_array", $array, $this->id, $this );
 
-		return $array;
+		/**
+		 * Filter the array of the ActivityPub object by class.
+		 *
+		 * @param array       $array  The array of the ActivityPub object.
+		 * @param int         $id     The ID of the ActivityPub object.
+		 * @param Base_Object $object The ActivityPub object.
+		 *
+		 * @return array The filtered array of the ActivityPub object.
+		 */
+		return \apply_filters( "activitypub_activity_{$class}_object_array", $array, $this->id, $this );
 	}
 
 	/**
@@ -698,11 +716,11 @@ public function to_json( $include_json_ld_context = true ) {
 		$array   = $this->to_array( $include_json_ld_context );
 		$options = \JSON_HEX_TAG | \JSON_HEX_AMP | \JSON_HEX_QUOT;
 
-		/*
-		* Options to be passed to json_encode()
-		*
-		* @param int $options The current options flags
-		*/
+		/**
+		 * Options to be passed to json_encode()
+		 *
+		 * @param int $options The current options flags.
+		 */
 		$options = \apply_filters( 'activitypub_json_encode_options', $options );
 
 		return \wp_json_encode( $array, $options );

includes/activity/extended-object/class-event.php

@@ -19,8 +19,8 @@
 class Event extends Base_Object {
 	// Human friendly minimal context for full Mobilizon compatible ActivityPub events.
 	const JSON_LD_CONTEXT = array(
-		'https://schema.org/',                   // The base context is schema.org, cause it is used a lot.
-		'https://www.w3.org/ns/activitystreams', // The ActivityStreams context overrides everyting also defined in schema.org.
+		'https://schema.org/',                   // The base context is schema.org, because it is used a lot.
+		'https://www.w3.org/ns/activitystreams', // The ActivityStreams context overrides everything also defined in schema.org.
 		array(                                   // The keys here override/extend the context even more.
 			'pt'                            => 'https://joinpeertube.org/ns#',
 			'mz'                            => 'https://joinmobilizon.org/ns#',
@@ -59,7 +59,7 @@ class Event extends Base_Object {
 	/**
 	 * Mobilizon compatible values for joinModeTypes.
 	 */
-	const JOIN_MODE_TYPES = array( 'free', 'restricted', 'external' ); // and 'invite', but not used by mobilizon atm
+	const JOIN_MODE_TYPES = array( 'free', 'restricted', 'external' ); // and 'invite', but not used by mobilizon atm.
 
 	/**
 	 * Allowed values for ical VEVENT STATUS.
@@ -109,8 +109,7 @@ class Event extends Base_Object {
 	);
 
 	/**
-	 * Event is an implementation of one of the
-	 * Activity Streams
+	 * Event is an implementation of one of the Activity Streams.
 	 *
 	 * @var string
 	 */
@@ -124,7 +123,7 @@ class Event extends Base_Object {
 	protected $name;
 
 	/**
-	 * The events contacts
+	 * The events contacts.
 	 *
 	 * @context {
 	 *   '@id'   => 'mz:contacts',
@@ -200,7 +199,7 @@ class Event extends Base_Object {
 	 * The event's status.
 	 *
 	 * @context https://www.w3.org/2002/12/cal/ical#status
-	 * @var enum
+	 * @var string
 	 */
 	protected $status;
 
@@ -263,6 +262,7 @@ class Event extends Base_Object {
 	 * The passed timezone is only set when it is a valid one, otherwise the site's timezone is used.
 	 *
 	 * @param string $timezone The timezone string to be set, e.g. 'Europe/Berlin'.
+	 * @return Event
 	 */
 	public function set_timezone( $timezone ) {
 		if ( in_array( $timezone, timezone_identifiers_list(), true ) ) {
@@ -275,9 +275,11 @@ public function set_timezone( $timezone ) {
 	}
 
 	/**
-	 * Custom setter for repliesModerationOption which also directy sets commentsEnabled accordingly.
+	 * Custom setter for repliesModerationOption which also directly sets commentsEnabled accordingly.
+	 *
+	 * @param string $type The type of the replies moderation option.
 	 *
-	 * @param string $type
+	 * @return Event
 	 */
 	public function set_replies_moderation_option( $type ) {
 		if ( in_array( $type, self::REPLIES_MODERATION_OPTION_TYPES, true ) ) {
@@ -297,7 +299,9 @@ public function set_replies_moderation_option( $type ) {
 	/**
 	 * Custom setter for commentsEnabled which also directly sets repliesModerationOption accordingly.
 	 *
-	 * @param bool $comments_enabled
+	 * @param bool $comments_enabled Whether comments are enabled.
+	 *
+	 * @return Event
 	 */
 	public function set_comments_enabled( $comments_enabled ) {
 		if ( is_bool( $comments_enabled ) ) {
@@ -317,7 +321,9 @@ public function set_comments_enabled( $comments_enabled ) {
 	/**
 	 * Custom setter for the ical status that checks whether the status is an ical event status.
 	 *
-	 * @param string $status
+	 * @param string $status The status of the event.
+	 *
+	 * @return Event
 	 */
 	public function set_status( $status ) {
 		if ( in_array( $status, self::ICAL_EVENT_STATUS_TYPES, true ) ) {
@@ -338,8 +344,10 @@ public function set_status( $status ) {
 	 *
 	 * Falls back to Mobilizons default category.
 	 *
-	 * @param string $category
-	 * @param bool   $mobilizon_compatibilty Whether the category must be compatibly with Mobilizon.
+	 * @param string $category               The category of the event.
+	 * @param bool   $mobilizon_compatibilty Optional. Whether the category must be compatibly with Mobilizon. Default true.
+	 *
+	 * @return Event
 	 */
 	public function set_category( $category, $mobilizon_compatibilty = true ) {
 		if ( $mobilizon_compatibilty ) {
@@ -356,7 +364,9 @@ public function set_category( $category, $mobilizon_compatibilty = true ) {
 	 *
 	 * Automatically sets the joinMode to true if called.
 	 *
-	 * @param string $url
+	 * @param string $url The URL for external participation.
+	 *
+	 * @return Event
 	 */
 	public function set_external_participation_url( $url ) {
 		if ( preg_match( '/^https?:\/\/.*/i', $url ) ) {

includes/activity/extended-object/class-place.php

@@ -86,6 +86,11 @@ class Place extends Base_Object {
 	 */
 	protected $address;
 
+	/**
+	 * Set the address of the place.
+	 *
+	 * @param array|string $address The address of the place.
+	 */
 	public function set_address( $address ) {
 		if ( is_string( $address ) || is_array( $address ) ) {
 			$this->address = $address;