diff --git a/src/atom-environment.coffee b/src/atom-environment.coffee
index bfc387348..8ebad4c4a 100644
--- a/src/atom-environment.coffee
+++ b/src/atom-environment.coffee
@@ -827,6 +827,9 @@ class AtomEnvironment extends Model
 
   # Essential: A flexible way to open a dialog akin to an alert dialog.
   #
+  # If the dialog is closed (via `Esc` key or `X` in the top corner) without selecting a button
+  # the first button will be clicked unless a "Cancel" or "No" button is provided.
+  #
   # ## Examples
   #
   # ```coffee
@@ -844,7 +847,7 @@ class AtomEnvironment extends Model
   #   * `buttons` (optional) Either an array of strings or an object where keys are
   #     button names and the values are callbacks to invoke when clicked.
   #
-  # Returns the chosen button index {Number} if the buttons option was an array.
+  # Returns the chosen button index {Number} if the buttons option is an array or the return value of the callback if the buttons option is an object.
   confirm: (params={}) ->
     @applicationDelegate.confirm(params)