phan: Fix phpdocs Phan can't parse (#37102)

A lot are things like `@returns` instead of `@return`, JS syntax like `@param {int}`, and punctuation like `@return array.`. One thing particularly of note is that when we have a doc comment for a hook, then later in the function a closure without a doc comment, Phan was thinking the hook doc belonged to the closure (and then complained that none of the `@param`s matched). We can fix that by adding a doc comment for the closure itself. WAF was already using some advanced syntax 👍, but they syntax they used was incompatible with Phan in a few places: * Phan doesn't like leading/trailing spaces in array shapes, so do like `array{int, int}` instead of `array{ int, int }`. * A few places they did `array<>` rather than `array{}`. * For some reason they were using `@template` where `@type` was intended.
Automattic · Apr 29, 2024 · 5c59a37 · 5c59a37
1 parent 2b79cbf
commit 5c59a37
Show file tree

Hide file tree

Showing 123 changed files with 419 additions and 369 deletions.
diff --git a/projects/packages/analyzer/.phan/baseline.php b/projects/packages/analyzer/.phan/baseline.php
@@ -10,23 +10,21 @@
 return [
     // # Issue statistics:
     // PhanUndeclaredProperty : 30+ occurrences
-    // PhanTypeMismatchArgument : 10+ occurrences
-    // PhanUndeclaredClassMethod : 9 occurrences
+    // PhanTypeMismatchArgument : 8 occurrences
     // PhanPossiblyUndeclaredVariable : 7 occurrences
     // PhanParamSignatureMismatch : 6 occurrences
     // PhanPluginDuplicateConditionalNullCoalescing : 6 occurrences
     // PhanTypeMismatchReturnProbablyReal : 6 occurrences
-    // PhanUndeclaredTypeParameter : 6 occurrences
+    // PhanUndeclaredClassMethod : 6 occurrences
+    // PhanUndeclaredMethod : 6 occurrences
     // PhanTypeArraySuspiciousNullable : 5 occurrences
     // PhanTypeMismatchArgumentNullable : 5 occurrences
-    // PhanUndeclaredMethod : 4 occurrences
+    // PhanUndeclaredTypeParameter : 4 occurrences
     // PhanDeprecatedEncapsVar : 2 occurrences
     // PhanNonClassMethodCall : 2 occurrences
     // PhanPluginDuplicateCatchStatementBody : 2 occurrences
     // PhanTypeMismatchDeclaredParam : 2 occurrences
     // PhanUndeclaredClassStaticProperty : 2 occurrences
-    // PhanUnextractableAnnotationElementName : 2 occurrences
-    // PhanUnextractableAnnotationSuffix : 2 occurrences
     // PhanPluginDuplicateExpressionAssignmentOperation : 1 occurrence
     // PhanPluginUseReturnValueInternalKnown : 1 occurrence
     // PhanTypeMismatchArgumentProbablyReal : 1 occurrence
@@ -41,7 +39,6 @@
         'scripts/jetpack-slurper.php' => ['PhanDeprecatedEncapsVar'],
         'scripts/jetpack-svn.php' => ['PhanPluginDuplicateConditionalNullCoalescing', 'PhanTypeArraySuspiciousNullable'],
         'src/Declarations/class-declaration.php' => ['PhanUndeclaredProperty'],
-        'src/Declarations/class-visitor.php' => ['PhanTypeMismatchArgument'],
         'src/Differences/class-class-const-missing.php' => ['PhanParamSignatureMismatch', 'PhanTypeMismatchArgument', 'PhanTypeMismatchReturnProbablyReal'],
         'src/Differences/class-class-const-moved.php' => ['PhanTypeMismatchArgument'],
         'src/Differences/class-class-method-deprecated.php' => ['PhanParamSignatureMismatch', 'PhanTypeMismatchReturnProbablyReal'],
@@ -57,7 +54,7 @@
         'src/class-declarations.php' => ['PhanPluginDuplicateCatchStatementBody'],
         'src/class-differences.php' => ['PhanNonClassMethodCall', 'PhanPossiblyUndeclaredVariable', 'PhanTypeMismatchArgumentNullable'],
         'src/class-invocations.php' => ['PhanPluginDuplicateCatchStatementBody'],
-        'src/class-utils.php' => ['PhanTypeMismatchArgument', 'PhanUndeclaredClassMethod', 'PhanUndeclaredMethod', 'PhanUndeclaredProperty', 'PhanUndeclaredTypeParameter', 'PhanUnextractableAnnotationElementName', 'PhanUnextractableAnnotationSuffix'],
+        'src/class-utils.php' => ['PhanTypeMismatchArgument', 'PhanUndeclaredMethod', 'PhanUndeclaredProperty', 'PhanUndeclaredTypeParameter'],
         'src/class-warnings.php' => ['PhanUndeclaredMethod'],
         'src/diff-generator.php' => ['PhanDeprecatedEncapsVar'],
     ],

diff --git a/projects/packages/analyzer/changelog/fix-phan-comment-errors b/projects/packages/analyzer/changelog/fix-phan-comment-errors
@@ -0,0 +1,5 @@
+Significance: patch
+Type: fixed
+Comment: Fix phpdoc comments to make Phan happier. No change to functionality.
+
+
diff --git a/projects/packages/analyzer/src/class-utils.php b/projects/packages/analyzer/src/class-utils.php
@@ -123,7 +123,7 @@ public static function maybe_stringify( $object ) {
 	/**
 	 * Check if a node has a docblock containing a specific comment string.
 	 *
-	 * @param PhpParser/Node $node    Current node we are parsing.
+	 * @param Node $node    Current node we are parsing.
 	 * @param string         $comment Comment to match.
 	 * @return boolean
 	 */
@@ -139,7 +139,7 @@ public static function has_doc_comment( $node, $comment ) {
 	 * Check if a node contains a call to a function name.
 	 * Any part of the function name will be matched.
 	 *
-	 * @param PhpParser/Node $node Current node we are parsing.
+	 * @param Node $node Current node we are parsing.
 	 * @param string         $name Function name to match.
 	 * @return boolean
 	 */

diff --git a/projects/packages/connection/.phan/baseline.php b/projects/packages/connection/.phan/baseline.php
@@ -26,7 +26,6 @@
     // PhanTypeMismatchArgumentInternal : 3 occurrences
     // PhanTypeMismatchArgumentNullable : 3 occurrences
     // PhanTypeObjectUnsetDeclaredProperty : 3 occurrences
-    // PhanCommentParamWithoutRealParam : 2 occurrences
     // PhanNonClassMethodCall : 2 occurrences
     // PhanPluginUnreachableCode : 2 occurrences
     // PhanPossiblyUndeclaredVariable : 2 occurrences
@@ -41,7 +40,6 @@
     // PhanPluginSimplifyExpressionBool : 1 occurrence
     // PhanTypeMismatchDeclaredParamNullable : 1 occurrence
     // PhanUndeclaredClassReference : 1 occurrence
-    // PhanUnextractableAnnotationSuffix : 1 occurrence
 
     // Currently, file_suppressions and directory_suppressions are the only supported suppressions
     'file_suppressions' => [
@@ -59,8 +57,8 @@
         'src/class-partner.php' => ['PhanTypeMismatchPropertyProbablyReal'],
         'src/class-plugin-storage.php' => ['PhanUndeclaredClassMethod'],
         'src/class-rest-authentication.php' => ['PhanTypeMismatchPropertyDefault', 'PhanTypeMismatchPropertyProbablyReal'],
-        'src/class-rest-connector.php' => ['PhanParamTooMany', 'PhanTypeMismatchArgument', 'PhanTypeMismatchArgumentProbablyReal', 'PhanTypeMismatchReturnProbablyReal', 'PhanUndeclaredClassMethod', 'PhanUnextractableAnnotationSuffix'],
-        'src/class-secrets.php' => ['PhanCommentParamWithoutRealParam', 'PhanNonClassMethodCall', 'PhanTypeMismatchArgument'],
+        'src/class-rest-connector.php' => ['PhanParamTooMany', 'PhanTypeMismatchArgument', 'PhanTypeMismatchArgumentProbablyReal', 'PhanTypeMismatchReturnProbablyReal', 'PhanUndeclaredClassMethod'],
+        'src/class-secrets.php' => ['PhanNonClassMethodCall', 'PhanTypeMismatchArgument'],
         'src/class-server-sandbox.php' => ['PhanPluginDuplicateConditionalNullCoalescing', 'PhanTypeMismatchArgument'],
         'src/class-tokens.php' => ['PhanImpossibleTypeComparison', 'PhanTypeMismatchArgumentInternal', 'PhanTypeMismatchReturn', 'PhanTypeMismatchReturnProbablyReal'],
         'src/class-tracking.php' => ['PhanPluginDuplicateConditionalNullCoalescing', 'PhanTypeMismatchArgumentProbablyReal', 'PhanTypeMismatchDefault', 'PhanTypePossiblyInvalidDimOffset'],

diff --git a/projects/packages/connection/changelog/fix-phan-comment-errors b/projects/packages/connection/changelog/fix-phan-comment-errors
@@ -0,0 +1,5 @@
+Significance: patch
+Type: fixed
+Comment: Fix phpdoc comments to make Phan happier. No change to functionality.
+
+
diff --git a/projects/packages/connection/src/class-package-version.php b/projects/packages/connection/src/class-package-version.php
@@ -12,7 +12,7 @@
  */
 class Package_Version {
 
-	const PACKAGE_VERSION = '2.7.4';
+	const PACKAGE_VERSION = '2.7.5-alpha';
 
 	const PACKAGE_SLUG = 'connection';
 

diff --git a/projects/packages/connection/src/class-rest-connector.php b/projects/packages/connection/src/class-rest-connector.php
@@ -938,7 +938,7 @@ public static function disconnect_site() {
 	 *
 	 * @since 1.29.0
 	 *
-	 * @return bool|WP_Error.
+	 * @return bool|WP_Error
 	 */
 	public static function update_user_token_permission_check() {
 		return Rest_Authentication::is_signed_with_blog_token()

diff --git a/projects/packages/connection/src/class-secrets.php b/projects/packages/connection/src/class-secrets.php
@@ -158,6 +158,7 @@ public function verify( $action, $secret_1, $user_id ) {
 		 */
 		do_action( 'jetpack_verify_secrets_begin', $action, $user );
 
+		/** Closure to run the 'fail' action and return an error. */
 		$return_error = function ( WP_Error $error ) use ( $action, $user ) {
 			/**
 			 * Verifying of the previously generated secret has failed.

diff --git a/projects/packages/constants/.phan/baseline.php b/projects/packages/constants/.phan/baseline.php
@@ -11,11 +11,9 @@
     // # Issue statistics:
     // PhanTypeMismatchArgumentProbablyReal : 3 occurrences
     // PhanTypeMismatchArgument : 2 occurrences
-    // PhanUnextractableAnnotationSuffix : 1 occurrence
 
     // Currently, file_suppressions and directory_suppressions are the only supported suppressions
     'file_suppressions' => [
-        'src/class-constants.php' => ['PhanUnextractableAnnotationSuffix'],
         'tests/php/test-constants.php' => ['PhanTypeMismatchArgument', 'PhanTypeMismatchArgumentProbablyReal'],
     ],
     // 'directory_suppressions' => ['src/directory_name' => ['PhanIssueName1', 'PhanIssueName2']] can be manually added if needed.

diff --git a/projects/packages/constants/changelog/fix-phan-comment-errors b/projects/packages/constants/changelog/fix-phan-comment-errors
@@ -0,0 +1,5 @@
+Significance: patch
+Type: fixed
+Comment: Fix phpdoc comments to make Phan happier. No change to functionality.
+
+
diff --git a/projects/packages/constants/src/class-constants.php b/projects/packages/constants/src/class-constants.php
@@ -29,7 +29,7 @@ class Constants {
 	 * @access public
 	 * @static
 	 *
-	 * @var array.
+	 * @var array
 	 */
 	public static $set_constants = array();
 

diff --git a/projects/packages/forms/.phan/baseline.php b/projects/packages/forms/.phan/baseline.php
@@ -20,7 +20,6 @@
     // PhanRedundantCondition : 4 occurrences
     // PhanTypeMismatchReturn : 3 occurrences
     // PhanTypePossiblyInvalidDimOffset : 3 occurrences
-    // PhanUnextractableAnnotationElementName : 3 occurrences
     // PhanPluginRedundantAssignment : 2 occurrences
     // PhanTypeConversionFromArray : 2 occurrences
     // PhanTypeMismatchArgumentNullableInternal : 2 occurrences
@@ -44,7 +43,7 @@
         'src/contact-form/class-contact-form-field.php' => ['PhanParamTooMany', 'PhanPluginDuplicateConditionalNullCoalescing', 'PhanPossiblyNullTypeMismatchProperty', 'PhanTypeConversionFromArray', 'PhanTypeMismatchArgument', 'PhanTypeMismatchReturnProbablyReal', 'PhanUndeclaredClassMethod', 'PhanUndeclaredProperty'],
         'src/contact-form/class-contact-form-plugin.php' => ['PhanPluginDuplicateAdjacentStatement', 'PhanPluginDuplicateConditionalNullCoalescing', 'PhanPluginRedundantAssignment', 'PhanTypeMismatchArgument', 'PhanTypeMismatchArgumentInternal', 'PhanTypeMismatchArgumentProbablyReal', 'PhanTypeMismatchReturn', 'PhanTypeMismatchReturnProbablyReal', 'PhanUndeclaredClassMethod'],
         'src/contact-form/class-contact-form-shortcode.php' => ['PhanPluginDuplicateConditionalNullCoalescing', 'PhanTypeMismatchReturnProbablyReal'],
-        'src/contact-form/class-contact-form.php' => ['PhanPluginDuplicateConditionalNullCoalescing', 'PhanPluginRedundantAssignment', 'PhanRedundantCondition', 'PhanTypeMismatchArgument', 'PhanTypeMismatchArgumentNullableInternal', 'PhanTypeMismatchReturnNullable', 'PhanTypeMismatchReturnProbablyReal', 'PhanUndeclaredClassMethod', 'PhanUnextractableAnnotationElementName'],
+        'src/contact-form/class-contact-form.php' => ['PhanPluginDuplicateConditionalNullCoalescing', 'PhanPluginRedundantAssignment', 'PhanRedundantCondition', 'PhanTypeMismatchArgument', 'PhanTypeMismatchArgumentNullableInternal', 'PhanTypeMismatchReturnNullable', 'PhanTypeMismatchReturnProbablyReal', 'PhanUndeclaredClassMethod'],
         'src/dashboard/class-dashboard-view-switch.php' => ['PhanUnreferencedUseNormal'],
         'src/dashboard/class-dashboard.php' => ['PhanUndeclaredClassMethod', 'PhanUndeclaredConstant'],
         'src/service/class-google-drive.php' => ['PhanTypeMismatchReturnProbablyReal'],

diff --git a/projects/packages/forms/changelog/fix-phan-comment-errors b/projects/packages/forms/changelog/fix-phan-comment-errors
@@ -0,0 +1,5 @@
+Significance: patch
+Type: fixed
+Comment: Fix phpdoc comments to make Phan happier. No change to functionality.
+
+
diff --git a/projects/packages/forms/src/contact-form/class-contact-form.php b/projects/packages/forms/src/contact-form/class-contact-form.php
@@ -446,8 +446,8 @@ public static function parse( $attributes, $content ) {
 	/**
 	 * Returns a success message to be returned if the form is sent via AJAX.
 	 *
-	 * @param int                 $feedback_id - the feedback ID.
-	 * @param object Contact_Form $form - the contact form.
+	 * @param int          $feedback_id - the feedback ID.
+	 * @param Contact_Form $form - the contact form.
 	 *
 	 * @return string $message
 	 */
@@ -476,8 +476,8 @@ public static function success_message( $feedback_id, $form ) {
 	 * Returns a compiled form with labels and values in a form of  an array
 	 * of lines.
 	 *
-	 * @param int                 $feedback_id - the feedback ID.
-	 * @param object Contact_Form $form - the form.
+	 * @param int          $feedback_id - the feedback ID.
+	 * @param Contact_Form $form - the form.
 	 *
 	 * @return array $lines
 	 */
@@ -569,8 +569,8 @@ public static function get_compiled_form( $feedback_id, $form ) {
 	 * Returns a compiled form with labels and values formatted for the email response
 	 * in a form of an array of lines.
 	 *
-	 * @param int                 $feedback_id - the feedback ID.
-	 * @param object Contact_Form $form - the form.
+	 * @param int          $feedback_id - the feedback ID.
+	 * @param Contact_Form $form - the form.
 	 *
 	 * @return array $lines
 	 */

diff --git a/projects/packages/jetpack-mu-wpcom/.phan/baseline.php b/projects/packages/jetpack-mu-wpcom/.phan/baseline.php
@@ -13,8 +13,8 @@
     // PhanTypeMismatchArgument : 15+ occurrences
     // PhanPluginDuplicateConditionalNullCoalescing : 8 occurrences
     // PhanTypeMismatchReturn : 6 occurrences
+    // PhanUndeclaredClassMethod : 5 occurrences
     // PhanTypeMismatchReturnProbablyReal : 4 occurrences
-    // PhanUndeclaredClassMethod : 4 occurrences
     // PhanNoopNew : 3 occurrences
     // PhanTypePossiblyInvalidDimOffset : 3 occurrences
     // PhanUndeclaredFunction : 3 occurrences
@@ -40,7 +40,6 @@
     // PhanTypeVoidArgument : 1 occurrence
     // PhanUndeclaredClassInCallable : 1 occurrence
     // PhanUndeclaredConstant : 1 occurrence
-    // PhanUnextractableAnnotationSuffix : 1 occurrence
 
     // Currently, file_suppressions and directory_suppressions are the only supported suppressions
     'file_suppressions' => [
@@ -56,7 +55,7 @@
         'src/features/launchpad/class-launchpad-task-lists.php' => ['PhanNoopArrayAccess', 'PhanPluginDuplicateConditionalNullCoalescing', 'PhanTypeMismatchDefault', 'PhanTypeMismatchReturn', 'PhanTypePossiblyInvalidDimOffset'],
         'src/features/launchpad/launchpad-task-definitions.php' => ['PhanRedundantCondition', 'PhanTypeArraySuspiciousNullable', 'PhanTypeComparisonToArray', 'PhanTypeMismatchArgument', 'PhanTypeMismatchArgumentInternal', 'PhanTypeMismatchReturn', 'PhanTypeMismatchReturnProbablyReal', 'PhanTypeMissingReturn', 'PhanTypePossiblyInvalidDimOffset'],
         'src/features/launchpad/launchpad.php' => ['PhanTypeArraySuspiciousNullable', 'PhanTypeMismatchArgument', 'PhanTypeMismatchReturn', 'PhanTypeMismatchReturnProbablyReal', 'PhanUndeclaredClassMethod'],
-        'src/features/marketplace-products-updater/class-marketplace-products-updater.php' => ['PhanTypeMismatchDimFetch', 'PhanTypeMismatchReturn', 'PhanUnextractableAnnotationSuffix'],
+        'src/features/marketplace-products-updater/class-marketplace-products-updater.php' => ['PhanTypeMismatchDimFetch', 'PhanTypeMismatchReturn'],
         'src/features/media/heif-support.php' => ['PhanPluginSimplifyExpressionBool'],
         'src/features/verbum-comments/class-verbum-comments.php' => ['PhanImpossibleTypeComparison', 'PhanNoopNew', 'PhanParamTooMany', 'PhanTypeMismatchArgumentProbablyReal', 'PhanUndeclaredFunction'],
         'src/features/wpcom-endpoints/class-wpcom-rest-api-v2-endpoint-launchpad.php' => ['PhanPluginDuplicateConditionalNullCoalescing'],

diff --git a/projects/packages/jetpack-mu-wpcom/changelog/fix-phan-comment-errors b/projects/packages/jetpack-mu-wpcom/changelog/fix-phan-comment-errors
@@ -0,0 +1,5 @@
+Significance: patch
+Type: fixed
+Comment: Fix phpdoc comments to make Phan happier. No change to functionality.
+
+
diff --git a/projects/packages/jetpack-mu-wpcom/package.json b/projects/packages/jetpack-mu-wpcom/package.json
@@ -1,7 +1,7 @@
 {
 	"private": true,
 	"name": "@automattic/jetpack-mu-wpcom",
-	"version": "5.27.0",
+	"version": "5.27.1-alpha",
 	"description": "Enhances your site with features powered by WordPress.com",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/packages/jetpack-mu-wpcom/#readme",
 	"bugs": {

diff --git a/projects/packages/jetpack-mu-wpcom/src/class-jetpack-mu-wpcom.php b/projects/packages/jetpack-mu-wpcom/src/class-jetpack-mu-wpcom.php
@@ -13,7 +13,7 @@
  * Jetpack_Mu_Wpcom main class.
  */
 class Jetpack_Mu_Wpcom {
-	const PACKAGE_VERSION = '5.27.0';
+	const PACKAGE_VERSION = '5.27.1-alpha';
 	const PKG_DIR         = __DIR__ . '/../';
 	const BASE_DIR        = __DIR__ . '/';
 	const BASE_FILE       = __FILE__;

diff --git a/...mu-wpcom/src/features/marketplace-products-updater/class-marketplace-products-updater.php b/...mu-wpcom/src/features/marketplace-products-updater/class-marketplace-products-updater.php
@@ -75,7 +75,7 @@ public static function transient_update_plugins( $transient ) {
 	 *
 	 * @param object $transient The update_themes transient object.
 	 *
-	 * @return object.
+	 * @return object Updated transient object.
 	 */
 	public static function transient_update_themes( $transient ) {
 		$updates = self::fetch_updates( 'themes' );

diff --git a/projects/packages/my-jetpack/.phan/baseline.php b/projects/packages/my-jetpack/.phan/baseline.php
@@ -19,7 +19,6 @@
     // PhanTypeMismatchReturn : 6 occurrences
     // PhanUndeclaredStaticProperty : 6 occurrences
     // PhanPluginDuplicateConditionalNullCoalescing : 5 occurrences
-    // PhanUnextractableAnnotation : 4 occurrences
     // PhanTypeMismatchReturnNullable : 3 occurrences
     // PhanImpossibleCondition : 2 occurrences
     // PhanNonClassMethodCall : 2 occurrences
@@ -30,7 +29,6 @@
     // PhanTypeMismatchArgumentNullableInternal : 1 occurrence
     // PhanUndeclaredClassStaticProperty : 1 occurrence
     // PhanUndeclaredConstant : 1 occurrence
-    // PhanUnextractableAnnotationSuffix : 1 occurrence
 
     // Currently, file_suppressions and directory_suppressions are the only supported suppressions
     'file_suppressions' => [
@@ -41,8 +39,8 @@
         'src/class-rest-product-data.php' => ['PhanParamTooMany', 'PhanTypeMismatchReturn'],
         'src/class-rest-products.php' => ['PhanParamTooMany', 'PhanPluginMixedKeyNoKey', 'PhanTypeMismatchReturn', 'PhanTypeMismatchReturnProbablyReal'],
         'src/class-rest-purchases.php' => ['PhanParamTooMany', 'PhanTypeMismatchReturn', 'PhanTypeMismatchReturnProbablyReal'],
-        'src/class-rest-zendesk-chat.php' => ['PhanParamTooMany', 'PhanUnextractableAnnotationSuffix'],
-        'src/class-wpcom-products.php' => ['PhanTypeMismatchReturnProbablyReal', 'PhanUnextractableAnnotation'],
+        'src/class-rest-zendesk-chat.php' => ['PhanParamTooMany'],
+        'src/class-wpcom-products.php' => ['PhanTypeMismatchReturnProbablyReal'],
         'src/products/class-anti-spam.php' => ['PhanTypeMismatchArgumentNullable', 'PhanTypeMismatchPropertyDefault'],
         'src/products/class-backup.php' => ['PhanTypeMismatchArgumentNullable', 'PhanTypeMismatchPropertyDefault'],
         'src/products/class-boost.php' => ['PhanTypeMismatchPropertyDefault'],

diff --git a/projects/packages/my-jetpack/changelog/fix-phan-comment-errors b/projects/packages/my-jetpack/changelog/fix-phan-comment-errors
@@ -0,0 +1,5 @@
+Significance: patch
+Type: fixed
+Comment: Fix phpdoc comments to make Phan happier. No change to functionality.
+
+
diff --git a/projects/packages/my-jetpack/src/class-rest-zendesk-chat.php b/projects/packages/my-jetpack/src/class-rest-zendesk-chat.php
@@ -8,6 +8,8 @@
 namespace Automattic\Jetpack\My_Jetpack;
 
 use Automattic\Jetpack\Connection\Client;
+use WP_Error;
+use WP_REST_Response;
 
 /**
  * Registers the REST routes for Zendesk Chat.
@@ -56,11 +58,11 @@ public function __construct() {
 	 * @access public
 	 * @static
 	 *
-	 * @return \WP_Error|true
+	 * @return WP_Error|true
 	 */
 	public static function chat_authentication_permissions_callback() {
 		if ( ! get_current_user_id() ) {
-			return new \WP_Error( 'unauthorized', 'You must be logged in to access this resource.', array( 'status' => 401 ) );
+			return new WP_Error( 'unauthorized', 'You must be logged in to access this resource.', array( 'status' => 401 ) );
 		}
 
 		return true;
@@ -69,7 +71,7 @@ public static function chat_authentication_permissions_callback() {
 	/**
 	 * Gets the chat authentication token.
 	 *
-	 * @return \WP_Error|object Object: { token: string }
+	 * @return WP_Error|WP_REST_Response { token: string }
 	 */
 	public static function get_chat_authentication() {
 		$authentication = get_transient( self::ZENDESK_AUTH_TOKEN );
@@ -91,7 +93,7 @@ public static function get_chat_authentication() {
 		$body          = json_decode( wp_remote_retrieve_body( $response ) );
 
 		if ( is_wp_error( $response ) || empty( $response['body'] ) ) {
-			return new \WP_Error( 'chat_authentication_failed', 'Chat authentication failed', array( 'status' => $response_code ) );
+			return new WP_Error( 'chat_authentication_failed', 'Chat authentication failed', array( 'status' => $response_code ) );
 		}
 
 		set_transient( self::ZENDESK_AUTH_TOKEN, $body, self::TRANSIENT_EXPIRY );
@@ -102,7 +104,7 @@ public static function get_chat_authentication() {
 	 * Calls `wpcom/v2/presales/chat?group=jp_presales` endpoint.
 	 * This endpoint returns whether or not the Jetpack presales chat group is available
 	 *
-	 * @return \WP_Error/object Object: { is_available: bool }
+	 * @return WP_Error|WP_REST_Response { is_available: bool }
 	 */
 	public static function get_chat_availability() {
 		$wpcom_endpoint    = '/presales/chat?group=jp_presales';
@@ -112,7 +114,7 @@ public static function get_chat_availability() {
 		$body              = json_decode( wp_remote_retrieve_body( $response ) );
 
 		if ( is_wp_error( $response ) || empty( $response['body'] ) ) {
-			return new \WP_Error( 'chat_config_data_fetch_failed', 'Chat config data fetch failed', array( 'status' => $response_code ) );
+			return new WP_Error( 'chat_config_data_fetch_failed', 'Chat config data fetch failed', array( 'status' => $response_code ) );
 		}
 
 		return rest_ensure_response( $body, 200 );