Add docblocks for Notification public functions

* Mark `dismiss` as an "extended" API because its use case is uncommon.
* Mark event handler functions as public because responding to a
  notification being displayed or dismissed is useful.

src/notification.coffee

@@ -19,18 +19,40 @@ class Notification
     unless _.isObject(@options) and not _.isArray(@options)
       throw new Error("Notification must be created with an options object: #{@options}")
 
+  ###
+  Section: Event Subscription
+  ###
+
+  # Public: Invoke the given callback when the notification is dismissed.
+  #
+  # * `callback` {Function} to be called when the notification is dismissed.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidDismiss: (callback) ->
     @emitter.on 'did-dismiss', callback
 
+  # Public: Invoke the given callback when the notification is displayed.
+  #
+  # * `callback` {Function} to be called when the notification is displayed.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidDisplay: (callback) ->
     @emitter.on 'did-display', callback
 
   getOptions: -> @options
 
+  ###
+  Section: Methods
+  ###
+
   # Public: Retrieves the {String} type.
+  #
+  # Returns a {String}.
   getType: -> @type
 
   # Public: Retrieves the {String} message.
+  #
+  # Returns a {String}.
   getMessage: -> @message
 
   getTimestamp: -> @timestamp
@@ -42,6 +64,8 @@ class Notification
       and @getType() is other.getType() \
       and @getDetail() is other.getDetail()
 
+  # Extended: Dismisses the notification, removing it from the UI. This will call all callbacks
+  # added via `onDidDismiss`.
   dismiss: ->
     return unless @isDismissable() and not @isDismissed()
     @dismissed = true