docs: fill in missing phpdoc on picker classes and REST helpers

Adds class-property and method-level phpdoc to bring the new picker
classes in line with the project's docblock conventions:

- MslsTranslationPickerTable: properties ($source_blog_id, $post_type,
  $search, $taxonomies_cache), constructor, get_columns,
  get_bulk_actions, prepare_items and no_items
- MslsTranslationPickerPage: BASE_SLUG / SCRIPT_HANDLE /
  PER_PAGE_OPTION / PER_PAGE_DEFAULT constants
- MslsPostListActions::init: bootstrap rationale and short-circuits
- MslsRestApi: get_list_route_args summary, apply_capability_filter
  parameter descriptions

No behaviour change.

Author: apermo

includes/MslsPostListActions.php

@@ -18,6 +18,11 @@
 class MslsPostListActions {
 
 	/**
+	 * Bootstraps the button injector on edit.php — short-circuits when MSLS
+	 * is excluded for the current blog, when no post_type is in the request,
+	 * when the current user can't create posts, or when no MSLS-active source
+	 * blogs exist.
+	 *
 	 * @codeCoverageIgnore
 	 */
 	public static function init(): void {

includes/MslsRestApi.php

@@ -115,6 +115,8 @@ private static function get_route_args(): array {
 	}
 
 	/**
+	 * Argument schema for the GET /untranslated-posts endpoint.
+	 *
 	 * @return array<string, array<string, mixed>>
 	 */
 	private static function get_list_route_args(): array {
@@ -221,11 +223,14 @@ public function check_list_permission( \WP_REST_Request $request ): bool {
 	}
 
 	/**
-	 * @param bool   $default
-	 * @param int    $source_post_id
+	 * Routes the default capability decision through the
+	 * msls_quick_create_capability filter so integrations can override it.
+	 *
+	 * @param bool   $default        Result of the default capability check.
+	 * @param int    $source_post_id Source post id, or 0 for list-style checks.
 	 * @param int    $source_blog_id
 	 * @param int    $target_blog_id
-	 * @param string $context
+	 * @param string $context        'read' for source-side checks, 'create' for target-side.
 	 *
 	 * @return bool
 	 */

includes/MslsTranslationPickerPage.php

@@ -18,12 +18,26 @@
  */
 class MslsTranslationPickerPage {
 
+	/**
+	 * Base of the per-post-type page slugs. The actual slug appended to the
+	 * URL is BASE_SLUG . '-' . $post_type — see {@see self::page_slug()}.
+	 */
 	const BASE_SLUG = 'msls-translation-picker';
 
+	/**
+	 * Script handle registered by {@see self::enqueue()} and reused as the
+	 * localization key for the script's bootstrap payload.
+	 */
 	const SCRIPT_HANDLE = 'msls-translation-picker';
 
+	/**
+	 * User-meta key behind the "Posts per page" Screen Options input.
+	 */
 	const PER_PAGE_OPTION = 'msls_tp_per_page';
 
+	/**
+	 * Page size used until the user picks a value via Screen Options.
+	 */
 	const PER_PAGE_DEFAULT = 20;
 
 	/**

includes/MslsTranslationPickerTable.php

@@ -24,17 +24,48 @@
  */
 class MslsTranslationPickerTable extends \WP_List_Table {
 
+	/**
+	 * Default page size used as a fallback when the user has not picked a
+	 * value via the screen-options dropdown.
+	 */
 	const PER_PAGE = 20;
 
+	/**
+	 * Source blog the listing queries (the picker reads from this site's
+	 * data while the page itself runs on the target blog).
+	 *
+	 * @var int
+	 */
 	protected int $source_blog_id;
 
+	/**
+	 * Post type being listed (read from the URL slug).
+	 *
+	 * @var string
+	 */
 	protected string $post_type;
 
+	/**
+	 * Optional title-search string forwarded to WP_Query as 's'.
+	 *
+	 * @var string
+	 */
 	protected string $search;
 
-	/** @var array<string, \WP_Taxonomy>|null */
+	/**
+	 * Per-request memo of the source-blog taxonomies whose admin column is
+	 * enabled. Resolved once and reused for both column headers and item
+	 * rendering.
+	 *
+	 * @var array<string, \WP_Taxonomy>|null
+	 */
 	protected ?array $taxonomies_cache = null;
 
+	/**
+	 * @param int    $source_blog_id Blog to read posts from.
+	 * @param string $post_type      Post type to query.
+	 * @param string $search         Optional title-search term.
+	 */
 	public function __construct( int $source_blog_id, string $post_type, string $search = '' ) {
 		parent::__construct(
 			array(
@@ -50,6 +81,13 @@ public function __construct( int $source_blog_id, string $post_type, string $sea
 		$this->search         = $search;
 	}
 
+	/**
+	 * Returns the column map for the table — checkbox, title, author, any
+	 * source-blog taxonomies that opted into show_admin_column, then status
+	 * and date.
+	 *
+	 * @return array<string, string>
+	 */
 	public function get_columns(): array {
 		$cols = array(
 			'cb'     => '<input type="checkbox" />',
@@ -99,12 +137,25 @@ protected function get_admin_column_taxonomies(): array {
 		return $this->taxonomies_cache;
 	}
 
+	/**
+	 * Registers the bulk action that the picker JS hijacks to create
+	 * drafts for every checked row.
+	 *
+	 * @return array<string, string>
+	 */
 	protected function get_bulk_actions(): array {
 		return array(
 			'msls_bulk_create' => __( 'Create drafts for selected', 'multisite-language-switcher' ),
 		);
 	}
 
+	/**
+	 * Loads the source-blog posts for the current page into $this->items.
+	 *
+	 * Honours hidden-column user prefs, the per-page screen option, the
+	 * search term and pagination. Already-translated post IDs are excluded
+	 * via TranslatedPostIdQuery against the target language.
+	 */
 	public function prepare_items(): void {
 		$columns               = $this->get_columns();
 		$hidden                = is_object( $this->screen ) ? get_hidden_columns( $this->screen ) : array();
@@ -258,6 +309,10 @@ protected function column_default( $item, $column_name ): string {
 		return '—';
 	}
 
+	/**
+	 * Renders the empty-state message — distinguishes between "search
+	 * returned nothing" and "every source post already has a translation".
+	 */
 	public function no_items(): void {
 		if ( '' !== $this->search ) {
 			esc_html_e( 'No posts match your search.', 'multisite-language-switcher' );