diff -u b/core/misc/ajax.js b/core/misc/ajax.js
--- b/core/misc/ajax.js
+++ b/core/misc/ajax.js
@@ -124,30 +124,50 @@
   /**
    * Provides Ajax page updating via jQuery $.ajax.
    *
-   * The Ajax request returns an array of commands encoded in JSON, which is
-   * then executed to make any changes that are necessary to the page.
-   *
-   * Drupal uses this file to enhance form elements with #ajax['url'] and
-   * #ajax['wrapper'] properties. If set, this file will automatically be
-   * included to provide Ajax capabilities.
-   *
-   * All Ajax objects on a page are accessible through Drupal.ajax.instances.
-   *
-   * @code
-   *    Drupal.behaviors.myCustomAJAXStuff = {
-   *      attach: function (context, settings) {
-   *        var myAjaxObject = Drupal.ajax(ajaxSettings);
-   *        myAjaxObject.commands.insert = function (ajax, response, status) {
-   *          new_content = $(response.data);
-   *          $('#my-wrapper').append(new_content);
-   *          alert('New content was appended to #my-wrapper');
-   *        }
-   *      }
-   *    };
-   * @endcode
+   * This function is designed to improve developer experience by wrapping the
+   * initialization of Drupal.Ajax objects and storing all created object in the
+   * Drupal.ajax.instances array.
+   *
+   * @example
+   * Drupal.behaviors.myCustomAJAXStuff = {
+   *   attach: function (context, settings) {
+   *
+   *     var ajaxSettings = {
+   *       url: 'my/url/path',
+   *       // If the old version of Drupal.ajax() needs to be used those
+   *       // properties can be added
+   *       base: 'myBase',
+   *       element: $(context).find('.someElement')
+   *     };
+   *
+   *     var myAjaxObject = Drupal.ajax(ajaxSettings);
+   *
+   *     // Declare a new Ajax command specifically for this Ajax object.
+   *     myAjaxObject.commands.insert = function (ajax, response, status) {
+   *       $('#my-wrapper').append(response.data);
+   *       alert('New content was appended to #my-wrapper');
+   *     };
+   *
+   *     // This command will remove this Ajax object from the page.
+   *     myAjaxObject.commands.destroyObject = function (ajax, response, status) {
+   *       Drupal.ajax.instances[this.instanceIndex] = null;
+   *     };
+   *
+   *     // Programmatically trigger the Ajax request.
+   *     myAjaxObject.execute();
+   *   }
+   * };
    *
    * @see Drupal.AjaxCommands
    *
+   * @param {object} settings
+   *   The settings object passed to Drupal.Ajax constructor.
+   * @param {string} [settings.base]
+   *   Base is passed to Drupal.Ajax constructor as the 'base' parameter.
+   * @param {HTMLElement} [settings.element]
+   *   Element parameter of Drupal.Ajax constructor, element on which
+   *   event listeners will be bound.
+   *
    * @return {Drupal.Ajax}
    */
   Drupal.ajax = function (settings) {
@@ -181,6 +201,29 @@
 
   /**
    * Ajax constructor.
+   *
+   * The Ajax request returns an array of commands encoded in JSON, which is
+   * then executed to make any changes that are necessary to the page.
+   *
+   * Drupal uses this file to enhance form elements with #ajax['url'] and
+   * #ajax['wrapper'] properties. If set, this file will automatically be
+   * included to provide Ajax capabilities.
+   *
+   * @constructor
+   *
+   * @param {string} [base]
+   *   Base parameter of Drupal.Ajax constructor
+   * @param {HTMLElement} [element]
+   *   Element parameter of Drupal.Ajax constructor, element on which
+   *   event listeners will be bound.
+   * @param {object} element_settings
+   * @param {string} element_settings.url
+   *   Target of the Ajax request.
+   * @param {string} [element_settings.event]
+   *   Event bound to settings.element which will trigger the Ajax request.
+   * @param {string} [element_settings.method]
+   *   Name of the jQuery method used to insert new content in the targeted
+   *   element.
    */
   Drupal.Ajax = function (base, element, element_settings) {
     var defaults = {