diff --git a/interface/src/scripting/SelectionScriptingInterface.cpp b/interface/src/scripting/SelectionScriptingInterface.cpp
index c15b5cde11..5856188868 100644
--- a/interface/src/scripting/SelectionScriptingInterface.cpp
+++ b/interface/src/scripting/SelectionScriptingInterface.cpp
@@ -44,13 +44,14 @@ SelectionScriptingInterface::SelectionScriptingInterface() {
 }
 
 /**jsdoc
+ * The type of a specific item in a selection list.
  * <table>
  *   <thead>
  *     <tr><th>Value</th><th>Description</th></tr>
  *   </thead>
  *   <tbody>
- *     <tr><td><code>"avatar"</code></td><td></td></tr>
- *     <tr><td><code>"entity"</code></td><td></td></tr>
+ *     <tr><td><code>"avatar"</code></td><td>The item is an avatar.</td></tr>
+ *     <tr><td><code>"entity"</code></td><td>The item is an entity.</td></tr>
  *   </tbody>
  * </table>
  * @typedef {string} Selection.ItemType
@@ -245,9 +246,10 @@ void SelectionScriptingInterface::printList(const QString& listName) {
 }
 
 /**jsdoc
+ * A selection list.
  * @typedef {object} Selection.SelectedItemsList
- * @property {Uuid[]} avatars - The IDs of the avatars in the selection.
- * @property {Uuid[]} entities - The IDs of the entities in the selection.
+ * @property {Uuid[]} avatars - The IDs of the avatars in the selection list.
+ * @property {Uuid[]} entities - The IDs of the entities in the selection list.
  */
 QVariantMap SelectionScriptingInterface::getSelectedItemsList(const QString& listName) const {
     QReadLocker lock(&_selectionListsLock);
@@ -438,18 +440,19 @@ bool SelectionHighlightStyle::fromVariantMap(const QVariantMap& properties) {
 }
 
 /**jsdoc
+ * The highlighting style of a selection list.
  * @typedef {object} Selection.HighlightStyle
- * @property {Color} outlineUnoccludedColor - Color of the specified highlight region.
- * @property {Color} outlineOccludedColor - ""
- * @property {Color} fillUnoccludedColor- ""
- * @property {Color} fillOccludedColor- ""
- * @property {number} outlineUnoccludedAlpha - Alpha value ranging from <code>0.0</code> (not visible) to <code>1.0</code> 
- *     (fully opaque) for the specified highlight region.
- * @property {number} outlineOccludedAlpha - ""
- * @property {number} fillUnoccludedAlpha - ""
- * @property {number} fillOccludedAlpha - ""
- * @property {number} outlineWidth - Width of the outline, in pixels.
- * @property {boolean} isOutlineSmooth - <code>true</code> to enable outline smooth fall-off.
+ * @property {Color} outlineUnoccludedColor=255,178,51 - Unoccluded outline color.
+ * @property {Color} outlineOccludedColor=255,178,51 - Occluded outline color.
+ * @property {Color} fillUnoccludedColor=51,178,255 - Unoccluded fill color.
+ * @property {Color} fillOccludedColor=51,178,255 - Occluded fill color.
+ * @property {number} outlineUnoccludedAlpha=0.9 - Unoccluded outline alpha, range <code>0.0</code> &ndash; <code>1.0</code>.
+ * @property {number} outlineOccludedAlpha=0.9 - Occluded outline alpha, range <code>0.0</code> &ndash; <code>1.0</code>.
+ * @property {number} fillUnoccludedAlpha=0.0 - Unoccluded fill alpha, range <code>0.0</code> &ndash; <code>1.0</code>.
+ * @property {number} fillOccludedAlpha=0.0 - Occluded fill alpha, range <code>0.0</code> &ndash; <code>1.0</code>.
+ * @property {number} outlineWidth=2 - Width of the outline, in pixels.
+ * @property {boolean} isOutlineSmooth=false - <code>true</code> to fade the outside edge of the outline, <code>false</code> 
+ *     to have a sharp edge.
  */
 QVariantMap SelectionHighlightStyle::toVariantMap() const {
     QVariantMap properties;
diff --git a/interface/src/scripting/SelectionScriptingInterface.h b/interface/src/scripting/SelectionScriptingInterface.h
index fcb4090184..4386ee5ee6 100644
--- a/interface/src/scripting/SelectionScriptingInterface.h
+++ b/interface/src/scripting/SelectionScriptingInterface.h
@@ -77,47 +77,45 @@ protected:
 };
 
 /**jsdoc
- * The <code>Selection</code> API provides a means of grouping together avatars and entities in named lists.
+ * The <code>Selection</code> API provides a means of grouping together and highlighting avatars and entities in named lists.
+ *
  * @namespace Selection
  *
  * @hifi-interface
  * @hifi-client-entity
  * @hifi-avatar
  *
- * @example <caption>Outline an entity when it is grabbed by a controller.</caption>
- * // Create a box and copy the following text into the entity's "Script URL" field.
+ * @example <caption>Outline an entity when it is grabbed by the mouse or a controller.</caption>
+ * // Create an entity and copy the following script into the entity's "Script URL" field.
+ * // Move the entity behind another entity to see the occluded outline.
  * (function () {
- *     print("Starting highlight script...............");
- *     var _this = this;
- *     var prevID = 0;
- *     var listName = "contextOverlayHighlightList";
- *     var listType = "entity";
- *
- *     _this.startNearGrab = function(entityID){
- *         if (prevID !== entityID) {
- *             Selection.addToSelectedItemsList(listName, listType, entityID);
- *             prevID = entityID;
- *         }
+ *     var LIST_NAME = "SelectionExample",
+ *         ITEM_TYPE = "entity",
+ *         HIGHLIGHT_STYLE = {
+ *             outlineUnoccludedColor: { red: 0, green: 180, blue: 239 },
+ *             outlineUnoccludedAlpha: 0.5,
+ *             outlineOccludedColor: { red: 239, green: 180, blue: 0 },
+ *             outlineOccludedAlpha: 0.5,
+ *             outlineWidth: 4
+ *         };
+ * 
+ *     Selection.enableListHighlight(LIST_NAME, HIGHLIGHT_STYLE);
+ * 
+ *     this.startNearGrab = function (entityID) {
+ *         Selection.addToSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID);
  *     };
- *
- *     _this.releaseGrab = function(entityID){
- *         if (prevID !== 0) {
- *             Selection.removeFromSelectedItemsList("contextOverlayHighlightList", listType, prevID);
- *             prevID = 0;
- *         }
+ * 
+ *     this.startDistanceGrab = function (entityID) {
+ *         Selection.addToSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID);
  *     };
- *
- *     var cleanup = function(){
- *         Entities.findEntities(MyAvatar.position, 1000).forEach(function(entity) {
- *             try {
- *                 Selection.removeListFromMap(listName);
- *             } catch (e) {
- *                 print("Error cleaning up.");
- *             }
- *         });
+ * 
+ *     this.releaseGrab = function (entityID) {
+ *         Selection.removeFromSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID);
  *     };
- *
- *     Script.scriptEnding.connect(cleanup);
+ * 
+ *     Script.scriptEnding.connect(function () {
+ *         Selection.removeListFromMap(LIST_NAME);
+ *     });
  * });
  */
 class SelectionScriptingInterface : public QObject, public Dependency {
@@ -127,121 +125,119 @@ public:
     SelectionScriptingInterface();
 
     /**jsdoc
-    * Get the names of all the selection lists.
-    * @function Selection.getListNames
-    * @returns {list[]} An array of names of all the selection lists.
-    */
+     * Gets the names of all current selection lists.
+     * @function Selection.getListNames
+     * @returns {string[]} The names of all current selection lists.
+     * @example <caption>List all the current selection lists.</caption>
+     * print("Selection lists: " + Selection.getListNames());
+     */
     Q_INVOKABLE QStringList getListNames() const;
 
     /**jsdoc
-    * Delete a named selection list.
-    * @function Selection.removeListFromMap
-    * @param {string} listName - The name of the selection list.
-    * @returns {boolean} <code>true</code> if the selection existed and was successfully removed, otherwise <code>false</code>.
-    */
+     * Deletes a selection list.
+     * @function Selection.removeListFromMap
+     * @param {string} listName - The name of the selection list to delete.
+     * @returns {boolean} <code>true</code> if the selection existed and was successfully removed, otherwise <code>false</code>.
+     */
     Q_INVOKABLE bool removeListFromMap(const QString& listName);
 
     /**jsdoc
-    * Add an item to a selection list.
-    * @function Selection.addToSelectedItemsList
-    * @param {string} listName - The name of the selection list to add the item to.
-    * @param {Selection.ItemType} itemType - The type of the item being added.
-    * @param {Uuid} id - The ID of the item to add to the selection.
-    * @returns {boolean} <code>true</code> if the item was successfully added, otherwise <code>false</code>.
-    */
+     * Adds an item to a selection list. The list is created if it doesn't exist.
+     * @function Selection.addToSelectedItemsList
+     * @param {string} listName - The name of the selection list to add the item to.
+     * @param {Selection.ItemType} itemType - The type of item being added.
+     * @param {Uuid} itemID - The ID of the item to add.
+     * @returns {boolean} <code>true</code> if the item was successfully added or already existed in the list, otherwise 
+     *     <code>false</code>.
+     */
     Q_INVOKABLE bool addToSelectedItemsList(const QString& listName, const QString& itemType, const QUuid& id);
+
     /**jsdoc
-    * Remove an item from a selection list.
-    * @function Selection.removeFromSelectedItemsList
-    * @param {string} listName - The name of the selection list to remove the item from.
-    * @param {Selection.ItemType} itemType - The type of the item being removed.
-    * @param {Uuid} id - The ID of the item to remove.
-    * @returns {boolean} <code>true</code> if the item was successfully removed, otherwise <code>false</code>.
-    *     <codefalse</code> is returned if the list doesn't contain any data.
-    */
+     * Removes an item from a selection list.
+     * @function Selection.removeFromSelectedItemsList
+     * @param {string} listName - The name of the selection list to remove the item from.
+     * @param {Selection.ItemType} itemType - The type of item being removed.
+     * @param {Uuid} itemID - The ID of the item to remove.
+     * @returns {boolean} <code>true</code> if the item was successfully removed or was not in the list, otherwise 
+     *     <code>false</code>.
+     */
     Q_INVOKABLE bool removeFromSelectedItemsList(const QString& listName, const QString& itemType, const QUuid& id);
+
     /**jsdoc
-    * Remove all items from a selection.
-    * @function Selection.clearSelectedItemsList
-    * @param {string} listName - The name of the selection list.
-    * @returns {boolean} <code>true</code> if the item was successfully cleared, otherwise <code>false</code>.
-    */
+     * Removes all items from a selection list.
+     * @function Selection.clearSelectedItemsList
+     * @param {string} listName - The name of the selection list.
+     * @returns {boolean} <code>true</code> always.
+     */
     Q_INVOKABLE bool clearSelectedItemsList(const QString& listName);
 
     /**jsdoc
-    * Print out the list of avatars and entities in a selection to the <em>debug log</em> (not the script log).
-    * @function Selection.printList
-    * @param {string} listName - The name of the selection list.
-    */
+     * Prints the list of avatars and entities in a selection to the program log (but not the Script Log window).
+     * @function Selection.printList
+     * @param {string} listName - The name of the selection list.
+     */
     Q_INVOKABLE void printList(const QString& listName);
 
     /**jsdoc
-    * Get the list of avatars and entities stored in a selection list.
-    * @function Selection.getSelectedItemsList
-    * @param {string} listName - The name of the selection list.
-    * @returns {Selection.SelectedItemsList} The content of a selection list. If the list name doesn't exist, the function 
-    *     returns an empty object with no properties.
-    */
+     * Gets the list of avatars and entities in a selection list.
+     * @function Selection.getSelectedItemsList
+     * @param {string} listName - The name of the selection list.
+     * @returns {Selection.SelectedItemsList} The content of the selection list if the list exists, otherwise an empty object.
+     */
     Q_INVOKABLE QVariantMap getSelectedItemsList(const QString& listName) const;
 
     /**jsdoc
-    * Get the names of the highlighted selection lists.
-    * @function Selection.getHighlightedListNames
-    * @returns {string[]} An array of names of the selection list currently highlight enabled.
-    */
+     * Gets the names of all current selection lists that have highlighting enabled.
+     * @function Selection.getHighlightedListNames
+     * @returns {string[]} The names of the selection lists that currently have highlighting enabled.
+     */
     Q_INVOKABLE QStringList getHighlightedListNames() const;
 
     /**jsdoc
-    * Enable highlighting for a selection list.
-    * If the selection list doesn't exist, it will be created.
-    * All objects in the list will be displayed with the highlight effect specified.
-    * The function can be called several times with different values in the style to modify it.<br />
-    * Note: This function implicitly calls {@link Selection.enableListToScene}.
-    * @function Selection.enableListHighlight
-    * @param {string} listName - The name of the selection list.
-    * @param {Selection.HighlightStyle} highlightStyle - The highlight style.
-    * @returns {boolean} true if the selection was successfully enabled for highlight.
-    */
+     * Enables highlighting for a selection list. All items in or subsequently added to the list are displayed with the 
+     * highlight effect specified. The method can be called multiple times with different values in the style to modify the 
+     * highlighting.
+     * <p>Note: This function implicitly calls {@link Selection.enableListToScene|enableListToScene}.</p>
+     * @function Selection.enableListHighlight
+     * @param {string} listName - The name of the selection list.
+     * @param {Selection.HighlightStyle} highlightStyle - The highlight style.
+     * @returns {boolean} <code>true</code> always.
+     */
     Q_INVOKABLE bool enableListHighlight(const QString& listName, const QVariantMap& highlightStyle);
 
     /**jsdoc
-    * Disable highlighting for the selection list.
-    * If the selection list doesn't exist or wasn't enabled for highlighting then nothing happens and <code>false</code> is
-    * returned.<br />
-    * Note: This function implicitly calls {@link Selection.disableListToScene}.
-    * @function Selection.disableListHighlight
-    * @param {string} listName - The name of the selection list.
-    * @returns {boolean} <code>true</code> if the selection was successfully disabled for highlight, otherwise 
-    *     <code>false</code>.
-    */
+     * Disables highlighting for a selection list.
+     * <p>Note: This function implicitly calls {@link Selection.disableListToScene|disableListToScene}.</p>
+     * @function Selection.disableListHighlight
+     * @param {string} listName - The name of the selection list.
+     * @returns {boolean} <code>true</code> always.
+     */
     Q_INVOKABLE bool disableListHighlight(const QString& listName);
+
     /**jsdoc
-    * Enable scene selection for the selection list.
-    * If the Selection doesn't exist, it will be created.
-    * All objects in the list will be sent to a scene selection.
-    * @function Selection.enableListToScene
-    * @param {string} listName - The name of the selection list.
-    * @returns {boolean} <code>true</code> if the selection was successfully enabled on the scene, otherwise <code>false</code>.
-    */
+     * Enables scene selection for a selection list. All items in or subsequently added to the list are sent to a scene 
+     * selection in the rendering engine for debugging purposes.
+     * @function Selection.enableListToScene
+     * @param {string} listName - The name of the selection list.
+     * @returns {boolean} <code>true</code> always.
+     */
     Q_INVOKABLE bool enableListToScene(const QString& listName);
 
     /**jsdoc
-    * Disable scene selection for the named selection.
-    * If the selection list doesn't exist or wasn't enabled on the scene then nothing happens and <code>false</code> is
-    * returned.
-    * @function Selection.disableListToScene
-    * @param {string} listName - The name of the selection list.
-    * @returns {boolean} true if the selection was successfully disabled on the scene, false otherwise.
-    */
+     * Disables scene selection for a selection list.
+     * @function Selection.disableListToScene
+     * @param {string} listName - The name of the selection list.
+     * @returns {boolean} <code>true</code> always.
+     */
     Q_INVOKABLE bool disableListToScene(const QString& listName);
 
     /**jsdoc
-    * Get the highlight style values for the a selection list.
-    * If the selection doesn't exist or hasn't been highlight enabled yet, an empty object is returned.
-    * @function Selection.getListHighlightStyle
-    * @param {string} listName - The name of the selection list.
-    * @returns {Selection.HighlightStyle} highlight style 
-    */
+     * Gets the current highlighting style for a selection list.
+     * @function Selection.getListHighlightStyle
+     * @param {string} listName - The name of the selection list.
+     * @returns {Selection.HighlightStyle} The highlight style of the selection list if the list exists and highlighting is 
+     *     enabled, otherwise an empty object.
+     */
     Q_INVOKABLE QVariantMap getListHighlightStyle(const QString& listName) const;
 
 
@@ -253,7 +249,7 @@ public:
 
 signals:
     /**jsdoc
-     * Triggered when a list's content changes.
+     * Triggered when a selection list's content changes or the list is deleted.
      * @function Selection.selectedItemsListChanged
      * @param {string} listName - The name of the selection list that changed.
      * @returns {Signal}
@@ -276,7 +272,6 @@ private:
     void setupHandler(const QString& selectionName);
     void removeHandler(const QString& selectionName);
 
-
 };
 
 #endif // hifi_SelectionScriptingInterface_h