Adjust some DocBlocks and whitespace

src/rest-api/stats/class-endpoint-posts.php

@@ -16,7 +16,6 @@
 use WP_REST_Request;
 use WP_REST_Response;
 use stdClass;
-use const _PHPStan_4f7beffdf\__;
 
 /**
  * The Stats API Posts endpoint.

src/services/class-base-service-endpoint.php

@@ -35,12 +35,15 @@ abstract class Base_Service_Endpoint {
 	/**
 	 * The API service that this endpoint belongs to.
 	 *
+	 * @since 3.17.0
+	 *
 	 * @var Base_API_Service
 	 */
 	protected $api_service;
 
 	/**
 	 * Flag to truncate the content of the request body.
+	 *
 	 * If set to true, the content of the request body will be truncated to a maximum length.
 	 *
 	 * @since 3.14.1

src/services/content-api/class-content-api-service.php

@@ -22,7 +22,6 @@
  * @since 3.17.0
  */
 class Content_API_Service extends Base_API_Service {
-
 	/**
 	 * Returns the base URL for the Parse.ly Content API, aka Public API.
 	 *

src/services/content-api/endpoints/class-content-api-base-endpoint.php

@@ -57,8 +57,9 @@ protected function get_query_args( array $args = array() ): array {
 	/**
 	 * Processes the response from the remote API.
 	 *
-	 * @param WP_HTTP_Response|WP_Error $response The response from the remote API.
+	 * @since 3.17.0
 	 *
+	 * @param WP_HTTP_Response|WP_Error $response The response from the remote API.
 	 * @return array<mixed>|WP_Error The processed response.
 	 */
 	protected function process_response( $response ) {

src/services/content-api/endpoints/class-endpoint-analytics-post-details.php

@@ -13,7 +13,7 @@
 use WP_Error;
 
 /**
- * The endpoint for the analytics post detail API request.
+ * The endpoint for the /analytics/post/detail API request.
  *
  * @since 3.17.0
  *
@@ -23,6 +23,8 @@ class Endpoint_Analytics_Post_Details extends Content_API_Base_Endpoint {
 	/**
 	 * Returns the endpoint for the API request.
 	 *
+	 * @since 3.17.0
+	 *
 	 * @return string
 	 */
 	public function get_endpoint(): string {
@@ -32,6 +34,8 @@ public function get_endpoint(): string {
 	/**
 	 * Executes the API request.
 	 *
+	 * @since 3.17.0
+	 *
 	 * @param array<mixed> $args The arguments to pass to the API request.
 	 * @return WP_Error|array<mixed> The response from the API request.
 	 */

src/services/content-api/endpoints/class-endpoint-analytics-posts.php

@@ -13,7 +13,7 @@
 use WP_Error;
 
 /**
- * The endpoint for the analytics/posts API request.
+ * The endpoint for the /analytics/posts API request.
  *
  * @since 3.17.0
  *
@@ -58,7 +58,7 @@ class Endpoint_Analytics_Posts extends Content_API_Base_Endpoint {
 
 	/**
 	 * Maximum limit for the number of records to return, to be
-	 * used in the `limit` parameter.
+	 * used in the limit parameter.
 	 *
 	 * @since 3.17.0
 	 *
@@ -67,7 +67,7 @@ class Endpoint_Analytics_Posts extends Content_API_Base_Endpoint {
 	public const MAX_LIMIT = 'max';
 
 	/**
-	 * Maximum period for the API request, to be used in the `period_start` parameter.
+	 * Maximum period for the API request, to be used in the period_start parameter.
 	 *
 	 * @since 3.17.0
 	 *
@@ -89,9 +89,9 @@ public function get_endpoint(): string {
 	/**
 	 * Returns the endpoint URL for the API request.
 	 *
-	 * This method appends the author, tag, and section parameters to the endpoint URL,
-	 * if they are set. Since Parsely API needs the multiple values for these parameters to share
-	 * the same key, we need to append them manually.
+	 * This method appends the author, tag, and section parameters to the
+	 * endpoint URL, if they are set. Since the Parse.ly API needs a key for
+	 * every value (e.g. tag=tag1&tag=tag2), we need to append them manually.
 	 *
 	 * @since 3.17.0
 	 *
@@ -128,6 +128,8 @@ protected function get_endpoint_url( array $args = array() ): string {
 	/**
 	 * Executes the API request.
 	 *
+	 * @since 3.17.0
+	 *
 	 * @param array<mixed> $args The arguments to pass to the API request.
 	 * @return WP_Error|array<mixed> The response from the API request.
 	 */
@@ -156,6 +158,8 @@ public function call( array $args = array() ) {
 	 * This is required because the Parsely API requires the multiple values for the author, tag,
 	 * and section parameters to share the same key.
 	 *
+	 * @since 3.17.0
+	 *
 	 * @param string        $url The URL to append the parameters to.
 	 * @param array<string> $params The parameters to append.
 	 * @param string        $param_name The name of the parameter.
@@ -170,6 +174,7 @@ protected function append_multiple_params_to_url( string $url, array $params, st
 				$url .= '&' . $param_name . '=' . $param;
 			}
 		}
+
 		return $url;
 	}
 }

src/services/content-api/endpoints/class-endpoint-referrers-post-detail.php

@@ -13,7 +13,7 @@
 use WP_Error;
 
 /**
- * The endpoint for the referrers post detail API request.
+ * The endpoint for the /referrers/post/detail API request.
  *
  * @since 3.17.0
  *
@@ -23,6 +23,8 @@ class Endpoint_Referrers_Post_Detail extends Content_API_Base_Endpoint {
 	/**
 	 * Returns the endpoint for the API request.
 	 *
+	 * @since 3.17.0
+	 *
 	 * @return string
 	 */
 	public function get_endpoint(): string {
@@ -32,6 +34,8 @@ public function get_endpoint(): string {
 	/**
 	 * Executes the API request.
 	 *
+	 * @since 3.17.0
+	 *
 	 * @param array<mixed> $args The arguments to pass to the API request.
 	 * @return WP_Error|array<mixed> The response from the API request.
 	 */

src/services/content-api/endpoints/class-endpoint-related.php

@@ -13,7 +13,7 @@
 use WP_Error;
 
 /**
- * The endpoint for the referrers post detail API request.
+ * The endpoint for the /related API request.
  *
  * @since 3.17.0
  *
@@ -23,6 +23,8 @@ class Endpoint_Related extends Content_API_Base_Endpoint {
 	/**
 	 * Returns the endpoint for the API request.
 	 *
+	 * @since 3.17.0
+	 *
 	 * @return string
 	 */
 	public function get_endpoint(): string {
@@ -32,6 +34,8 @@ public function get_endpoint(): string {
 	/**
 	 * Executes the API request.
 	 *
+	 * @since 3.17.0
+	 *
 	 * @param array<mixed> $args The arguments to pass to the API request.
 	 * @return WP_Error|array<mixed> The response from the API request.
 	 */

src/services/content-api/endpoints/class-endpoint-validate.php

@@ -35,7 +35,8 @@ public function get_endpoint(): string {
 	/**
 	 * Returns the query arguments for the API request.
 	 *
-	 * We want to validate the API key and secret, so we don't need to send any query arguments.
+	 * We want to validate the API key and secret, so we don't need to send any
+	 * query arguments.
 	 *
 	 * @since 3.17.0
 	 *
@@ -48,7 +49,9 @@ public function get_query_args( array $args = array() ): array {
 
 	/**
 	 * Queries the Parse.ly API credentials validation endpoint.
-	 * The API will return a 200 response if the credentials are valid and a 403 response if they are not.
+	 *
+	 * The API will return a 200 response if the credentials are valid and a 403
+	 * response if they are not.
 	 *
 	 * @since 3.17.0
 	 *
@@ -68,7 +71,6 @@ private function api_validate_credentials( string $api_key, string $secret_key )
 			return $response;
 		}
 
-
 		if ( false === $response['success'] ) {
 			return new WP_Error(
 				$response['code'] ?? 403,
@@ -94,6 +96,8 @@ protected function process_response( $response ) {
 	/**
 	 * Executes the API request.
 	 *
+	 * @since 3.17.0
+	 *
 	 * @param array<mixed> $args The arguments to pass to the API request.
 	 * @return WP_Error|array<mixed> The response from the API request.
 	 */

src/services/suggestions-api/class-suggestions-api-service.php

@@ -75,8 +75,8 @@ public function get_brief_suggestions( string $title, string $content, $options
 	}
 
 	/**
-	 * Generates titles (headlines) for a given content using the
-	 * Parse.ly Content Suggestion API.
+	 * Gets titles (headlines) for a given content using the Parse.ly Content
+	 * Suggestion API.
 	 *
 	 * @since 3.13.0
 	 * @since 3.17.0 Updated to use the new API service.
@@ -101,9 +101,9 @@ public function get_title_suggestions( string $content, $options = array() ) {
 	 *
 	 * @param string                                    $content             The content to generate links for.
 	 * @param Endpoint_Suggest_Linked_Reference_Options $options             The options to pass to the API request.
-	 * @param string[]                                  $url_exclusion_list  A list of URLs to exclude from the suggestions.
+	 * @param array<string>                             $url_exclusion_list  A list of URLs to exclude from the suggestions.
 	 *
-	 * @return Smart_Link[]|WP_Error The response from the remote API, or a WP_Error
+	 * @return array<Smart_Link>|WP_Error The response from the remote API, or a WP_Error
 	 *                                    object if the response is an error.
 	 */
 	public function get_smart_links( string $content, $options = array(), array $url_exclusion_list = array() ) {

src/services/suggestions-api/endpoints/class-endpoint-suggest-brief.php

@@ -13,7 +13,7 @@
 use WP_Error;
 
 /**
- * The endpoint for the suggest-brief API request.
+ * The endpoint for the /suggest-brief API request.
  *
  * @since 3.17.0
  *

src/services/suggestions-api/endpoints/class-endpoint-suggest-headline.php

@@ -13,7 +13,7 @@
 use WP_Error;
 
 /**
- * The endpoint for the suggest headline API request.
+ * The endpoint for the /suggest-headline API request.
  *
  * @since 3.17.0
  *
@@ -45,8 +45,8 @@ public function get_endpoint(): string {
 	}
 
 	/**
-	 * Generates titles (headlines) for a given content using the
-	 * Parse.ly Content Suggestion API.
+	 * Gets titles (headlines) for a given content using the Parse.ly Content
+	 * Suggestion API.
 	 *
 	 * @since 3.13.0
 	 * @since 3.17.0 Updated to use the new API service.

src/services/suggestions-api/endpoints/class-endpoint-suggest-linked-reference.php

@@ -18,7 +18,7 @@
  *
  * @since 3.17.0
  *
- * @link https://content-suggestions-api.parsely.net/prod/docs#/default/suggest_headline_suggest_headline_post
+ * @link https://content-suggestions-api.parsely.net/prod/docs#/default/suggest_linked_reference_suggest_linked_reference_post
  *
  * @phpstan-type Traffic_Source = array{
  *     source: string,
@@ -45,16 +45,16 @@ public function get_endpoint(): string {
 	}
 
 	/**
-	 * Gets suggested smart links for the given content.
+	 * Gets suggested smart links for the given content using the Parse.ly
+	 * Content Suggestion API.
 	 *
 	 * @since 3.14.0
 	 * @since 3.17.0 Updated to use the new API service.
 	 *
 	 * @param string                                    $content             The content to generate links for.
 	 * @param Endpoint_Suggest_Linked_Reference_Options $options The options to pass to the API request.
-	 * @param string[]                                  $url_exclusion_list  A list of URLs to exclude from the suggestions.
-	 *
-	 * @return Smart_Link[]|WP_Error The response from the remote API, or a WP_Error
+	 * @param array<string>                             $url_exclusion_list  A list of URLs to exclude from the suggestions.
+	 * @return array<Smart_Link>|WP_Error The response from the remote API, or a WP_Error
 	 *                                    object if the response is an error.
 	 */
 	public function get_links(

src/services/suggestions-api/endpoints/class-suggestions-api-base-endpoint.php

@@ -52,7 +52,7 @@ protected function get_request_options( string $method ): array {
 	/**
 	 * Returns the common query arguments to send to the remote API.
 	 *
-	 * This method append the API key and secret to the query arguments.
+	 * This method appends the API key and secret to the query arguments.
 	 *
 	 * @since 3.17.0
 	 *
@@ -71,8 +71,9 @@ protected function get_query_args( array $args = array() ): array {
 	/**
 	 * Processes the response from the remote API.
 	 *
-	 * @param WP_HTTP_Response|WP_Error $response The response from the remote API.
+	 * @since 3.17.0
 	 *
+	 * @param WP_HTTP_Response|WP_Error $response The response from the remote API.
 	 * @return array<mixed>|WP_Error The processed response.
 	 */
 	protected function process_response( $response ) {