Issue #3455342 by vladimiraus, bharath-kondeti, smustgrave: Improve...

Issue #3455342 by vladimiraus, bharath-kondeti, smustgrave: Improve Drupal\Core\Ajax\MessageCommand API documentation

core/lib/Drupal/Core/Ajax/MessageCommand.php

@@ -7,21 +7,59 @@
 /**
  * AJAX command for a JavaScript Drupal.message() call.
  *
- * Developers should be extra careful if this command and
- * \Drupal\Core\Ajax\AnnounceCommand are included in the same response. Unless
- * the `announce` option is set to an empty string (''), this command will
- * result in the message being announced to screen readers. When combined with
- * AnnounceCommand, this may result in unexpected behavior. Manual testing with
- * a screen reader is strongly recommended.
+ * AJAX command that allows you to add messages from an Ajax response. The command will create a new Drupal.Message() object and call its addMessage() method.
  *
+ * Usage examples:
  * Here are examples of how to suppress announcements:
  * @code
+ *   $response = new AjaxResponse();
+ *
+ *   // A status message added in the default location.
+ *   $response->addCommand(new MessageCommand('Your changes have been saved.'));
+ *
+ *   // A warning message added in the default location.
+ *   $response->addCommand(new MessageCommand('There was a problem. Save your work.', NULL, ['type' => 'warning']));
+ *
+ *   // A status message added an alternate location.
+ *   $response->addCommand(new MessageCommand('Hey look over here!', '#alternate-message-container'));
+ *
+ *   // An error added in an alternate location.
+ *   $response->addCommand(new MessageCommand('Open the pod bay doors, HAL.',  '#alternate-message-container', ['type' => 'error']));
+ * @endcode
+ *
+ * By default, previous messages in a location are cleared before the message
+ * is added. If you would like to leave the previous messages in a location,
+ * you may do so by setting the fourth parameter to FALSE:
+ * Here are examples of how to suppress announcements:
+ * @code
+ *   $response->addCommand(new MessageCommand('Hey look over here.', NULL, ['type' => 'error'], FALSE));
+ * @endcode
+ *
+ * Developers should take care when using MessageCommand and AnnounceCommand 
+ * together in the same AJAX response. Unless the "announce" option is set to
+ * an empty string (''), this command will result in the message being
+ * announced to screen readers. When combined with AnnounceCommand, this may
+ * result in unexpected behavior. Manual testing with a screen reader is
+ * strongly recommended.
+ *
+ * If you wish to display a message without the text being announced to screen
+ * readers, add options.announce = '' (i.e. an empty string):
+ * @code
  *   $command = new MessageCommand("I won't be announced", NULL, [
  *     'announce' => '',
  *   ]);
  * @endcode
  *
+ * If you wish to set the announcement priority to assertive, you can do that
+ * this way: 
+ * @code
+ *   $response->addCommand(new MessageCommand('You added 3 cat pics.', '.js-media-library-messages', [
+ *     'priority' => 'assertive',
+ *   ]);
+ * @endcode
+ *
  * @see \Drupal\Core\Ajax\AnnounceCommand
+ * @see https://www.drupal.org/docs/develop/drupal-apis/ajax-api/core-ajax-callback-commands#s-messagecommand
  *
  * @ingroup ajax
  */