tweak documentation for viewlists

IPython/html/static/widgets/js/widget.js

@@ -594,13 +594,14 b' define(["widgets/js/manager",'
 
     var ViewList = function(create_view, remove_view, context) {
         // * create_view and remove_view are default functions called when adding or removing views
-        // * create_view takes a model and creates a view or a promise for a view for that model
-        // * remove_view takes a view and destroys it (including calling `.remove()`)
-        // * each time the update() function is called with a new list, the create and destroy
+        // * create_view takes a model and returns a view or a promise for a view for that model
+        // * remove_view takes a view and destroys it (including calling `view.remove()`)
+        // * each time the update() function is called with a new list, the create and remove
         //   callbacks will be called in an order so that if you append the views created in the
-        //   create callback, you will duplicate the order of the list.
-        // * the remove callback defaults to just removing the view (if you pass in null)
-        // * the context defaults to the ViewList.  If you pass another context, the create and remove
+        //   create callback and remove the views in the remove callback, you will duplicate 
+        //   the order of the list.
+        // * the remove callback defaults to just removing the view (e.g., pass in null for the second parameter)
+        // * the context defaults to the created ViewList.  If you pass another context, the create and remove
         //   will be called in that context.
 
         this.initialize.apply(this, arguments);
@@ -653,7 +654,7 b' define(["widgets/js/manager",'
         },
 
         remove: function() {
-            // removes every view in our list; convenience function for `.update([])`
+            // removes every view in the list; convenience function for `.update([])`
             // that should be faster
             // returns a promise that resolves after this removal is done
             var that = this;