Changeset 42708

Timestamp:

02/13/2018 03:37:07 PM (7 years ago)

Author:

atimmer

Message:

Docs: Improve JSDoc for wp-admin/js/user-suggest.js.

Props timhavinga.
Fixes #43270.

File:

• trunk/src/wp-admin/js/user-suggest.js (modified) (2 diffs)

trunk/src/wp-admin/js/user-suggest.js

@@ -1 +1 @@
 /* global ajaxurl, current_site_id, isRtl */
+/**
+ * Suggests users in a multisite environment.
+ *
+ * For input fields where the admin can select a user based on email or
+ * username, this script shows an autocompletion menu for these inputs. Should
+ * only be used in a multisite environment. Only users in the currently active
+ * site are shown.
+ *
+ * @since 3.4.0
+ */
 
 (function( $ ) {
@@ -9 +19 @@
             position.at = 'right bottom';
         }
+
+        /**
+         * Adds an autocomplete function to input fields marked with the class
+         * 'wp-suggest-user'.
+         *
+         * A minimum of two characters is required to trigger
+         * the suggestions. The autocompletion menu is shown at the left bottom of the input
+         * field. On RTL installations, it is shown at the right top.
+         * Adds the class 'open' to the input field when the autocompletion menu
+         * is shown.
+         *
+         * Does a backend call to retrieve the users.
+         *
+         * Optional data-attributes:
+         * - data-autocomplete-type (add, search)
+         *   The action that is going to be performed: search for existing users
+         *   or add a new one. Default: add
+         * - data-autocomplete-field (user_login, user_email)
+         *   The field that is returned as the value for the suggestion.
+         *   Default: user_login
+         *
+         * @see wp-admin/includes/admin-actions.php:wp_ajax_autocomplete_user()
+         */
         $( '.wp-suggest-user' ).each( function(){
             var $this = $( this ),