         return callback("Permission denied")
 
   api.trash_entity = (session, params, callback) ->
+    ###
+    Move the entity into or out of the trash, depending on the value of the
+    boolean params.trash.
+    ###
     unless utils.is_authenticated(session)
       return callback("Permission denied")
     for key in ["group", "application", "entity", "trash"]

            return callback(null)
      
  api.cancel_deletion = (session, deletion_request_id, callback) ->
    unless utils.is_authenticated(session)
      return callback("Permission denied")
    schema.DeletionRequest.findOne {_id: deletion_request_id}, (err, dr) ->

          return callback(null, clear_notices.concat(notifications))

  api.request_deletion = (session, params, callback) ->
    ###
    Request deletion.  If the receiving application's policy permits, delete
    immediately; otherwise, create a DeletionRequest and associated
    notifications.
    ###
    unless utils.is_authenticated(session)
      return callback("Permission denied")
    for key in ["group", "application", "entity", "url", "title"]
