Connectors: Refine PHPDoc consistency across connector shape documentation.

gziolo · claude · gziolo · commit fadd350d6129 · 2026-03-12T07:01:19.000+01:00
- Simplify get_all_registered() @return to a one-liner, keeping @phpstan-return for static analysis — avoids maintaining a duplicate expanded shape on an internal method marked "do not use directly" - Order $authentication before $plugin consistently across all PHPDoc blocks, matching the actual construction order in register() - Fix @return array|null typo on get_all_registered() which never returns null Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
diff --git a/src/wp-includes/class-wp-connector-registry.php b/src/wp-includes/class-wp-connector-registry.php
@@ -70,7 +70,7 @@ final class WP_Connector_Registry {
 	 *         @type string $method          Required. The authentication method: 'api_key' or 'none'.
 	 *         @type string $credentials_url Optional. URL where users can obtain API credentials.
 	 *     }
-	 *     @type array  $plugin {
+	 *     @type array  $plugin         {
 	 *         Optional. Plugin data for install/activate UI.
 	 *
 	 *         @type string $slug The WordPress.org plugin slug.
@@ -208,31 +208,8 @@ public function unregister( string $id ): ?array {
 	 *
 	 * @see wp_get_connectors()
 	 *
-	 * @return array {
-	 *     Connector settings keyed by connector ID.
+	 * @return array Connector settings keyed by connector ID.
 	 *
-	 *     @type array ...$0 {
-	 *         Data for a single connector.
-	 *
-	 *         @type string $name           The connector's display name.
-	 *         @type string $description    The connector's description.
-	 *         @type string $logo_url       Optional. URL to the connector's logo image.
-	 *         @type string $type           The connector type. Currently, only 'ai_provider' is supported.
-	 *         @type array  $plugin         {
-	 *             Optional. Plugin data for install/activate UI.
-	 *
-	 *             @type string $slug       The WordPress.org plugin slug.
-	 *         }
-	 *         @type array  $authentication {
-	 *             Authentication configuration. When method is 'api_key', includes
-	 *             credentials_url and setting_name. When 'none', only method is present.
-	 *
-	 *             @type string $method          The authentication method: 'api_key' or 'none'.
-	 *             @type string $credentials_url Optional. URL where users can obtain API credentials.
-	 *             @type string $setting_name    Optional. The setting name for the API key.
-	 *         }
-	 *     }
-	 * }
 	 * @phpstan-return array<string, Connector>
 	 */
 	public function get_all_registered(): array {
diff --git a/src/wp-includes/connectors.php b/src/wp-includes/connectors.php
@@ -44,11 +44,6 @@ function wp_is_connector_registered( string $id ): bool {
  *     @type string $description    The connector's description.
  *     @type string $logo_url       Optional. URL to the connector's logo image.
  *     @type string $type           The connector type. Currently, only 'ai_provider' is supported.
- *     @type array  $plugin {
- *         Optional. Plugin data for install/activate UI.
- *
- *         @type string $slug The WordPress.org plugin slug.
- *     }
  *     @type array  $authentication {
  *         Authentication configuration. When method is 'api_key', includes
  *         credentials_url and setting_name. When 'none', only method is present.
@@ -57,6 +52,11 @@ function wp_is_connector_registered( string $id ): bool {
  *         @type string $credentials_url Optional. URL where users can obtain API credentials.
  *         @type string $setting_name    Optional. The setting name for the API key.
  *     }
+ *     @type array  $plugin         {
+ *         Optional. Plugin data for install/activate UI.
+ *
+ *         @type string $slug The WordPress.org plugin slug.
+ *     }
  * }
  * @phpstan-return ?array{
  *     name: non-empty-string,
@@ -99,11 +99,6 @@ function wp_get_connector( string $id ): ?array {
  *         @type string      $description    The connector's description.
  *         @type string      $logo_url       Optional. URL to the connector's logo image.
  *         @type string      $type           The connector type. Currently, only 'ai_provider' is supported.
- *         @type array       $plugin {
- *             Optional. Plugin data for install/activate UI.
- *
- *             @type string $slug The WordPress.org plugin slug.
- *         }
  *         @type array       $authentication {
  *             Authentication configuration. When method is 'api_key', includes
  *             credentials_url and setting_name. When 'none', only method is present.
@@ -112,6 +107,11 @@ function wp_get_connector( string $id ): ?array {
  *             @type string $credentials_url Optional. URL where users can obtain API credentials.
  *             @type string $setting_name    Optional. The setting name for the API key.
  *         }
+ *         @type array       $plugin         {
+ *             Optional. Plugin data for install/activate UI.
+ *
+ *             @type string $slug The WordPress.org plugin slug.
+ *         }
  *     }
  * }
  * @phpstan-return array<string, array{
