From c19ed790665ad123d6fb52e79051a68534befe65 Mon Sep 17 00:00:00 2001 From: Ross Allen Date: Wed, 8 Jun 2016 16:36:37 -0700 Subject: [PATCH] Complete documentation for Notification creation Notifications support several options that were yet to be documented: `buttons`, `description`, and `stack`. Add descriptions for each option and its defaults (where applicable, e.g. .buttons.className). `stack` is technically available on all notification types, but it doesn't make sense to use it on types other than 'error' and 'fatal'. Therefore it's documented only in those two cases. The usage and expected display, like preformatted vs. Markdown, taken from [atom/notifications/lib/notification-element.coffee][1]. [1]: https://github.com/atom/notifications/blob/v0.64.1/lib/notification-element.coffee --- src/notification-manager.coffee | 74 ++++++++++++++++++++++++++++----- 1 file changed, 64 insertions(+), 10 deletions(-) diff --git a/src/notification-manager.coffee b/src/notification-manager.coffee index 3d8b1895c..7b712e6bf 100644 --- a/src/notification-manager.coffee +++ b/src/notification-manager.coffee @@ -33,8 +33,18 @@ class NotificationManager # # * `message` A {String} message # * `options` (optional) An options {Object} with the following keys: - # * `detail` (optional) A {String} with additional details about the - # notification. + # * `buttons` (optional) An {Array} of {Object} where each {Object} has the + # following options: + # * `className` (optional) {String} additional class name add to the + # button. It will already receive `btn btn-success`. + # * `onClick` (optional) {Function} callback to call when the button is + # clicked. The context will be set to the {NotificationElement} + # instance. + # * `text` {String} inner text for the button + # * `description` (optional) A {String} that will be rendered as Markdown + # to describe the notification. + # * `detail` (optional) A preformatted {String} that will be rendered as + # plain text with details about the notification. # * `dismissable` (optional) A {Boolean} indicating whether this # notification can be dismissed by the user. Defaults to `false`. # * `icon` (optional) A {String} name of an icon from Octicons to display @@ -46,8 +56,18 @@ class NotificationManager # # * `message` A {String} message # * `options` (optional) An options {Object} with the following keys: - # * `detail` (optional) A {String} with additional details about the - # notification. + # * `buttons` (optional) An {Array} of {Object} where each {Object} has the + # following options: + # * `className` (optional) {String} additional class name add to the + # button. It will already receive `btn btn-info`. + # * `onClick` (optional) {Function} callback to call when the button is + # clicked. The context will be set to the {NotificationElement} + # instance. + # * `text` {String} inner text for the button + # * `description` (optional) A {String} that will be rendered as Markdown + # to describe the notification. + # * `detail` (optional) A preformatted {String} that will be rendered as + # plain text with details about the notification. # * `dismissable` (optional) A {Boolean} indicating whether this # notification can be dismissed by the user. Defaults to `false`. # * `icon` (optional) A {String} name of an icon from Octicons to display @@ -59,8 +79,18 @@ class NotificationManager # # * `message` A {String} message # * `options` (optional) An options {Object} with the following keys: - # * `detail` (optional) A {String} with additional details about the - # notification. + # * `buttons` (optional) An {Array} of {Object} where each {Object} has the + # following options: + # * `className` (optional) {String} additional class name add to the + # button. It will already receive `btn btn-warning`. + # * `onClick` (optional) {Function} callback to call when the button is + # clicked. The context will be set to the {NotificationElement} + # instance. + # * `text` {String} inner text for the button + # * `description` (optional) A {String} that will be rendered as Markdown + # to describe the notification. + # * `detail` (optional) A preformatted {String} that will be rendered as + # plain text with details about the notification. # * `dismissable` (optional) A {Boolean} indicating whether this # notification can be dismissed by the user. Defaults to `false`. # * `icon` (optional) A {String} name of an icon from Octicons to display @@ -72,12 +102,24 @@ class NotificationManager # # * `message` A {String} message # * `options` (optional) An options {Object} with the following keys: - # * `detail` (optional) A {String} with additional details about the - # notification. + # * `buttons` (optional) An {Array} of {Object} where each {Object} has the + # following options: + # * `className` (optional) {String} additional class name add to the + # button. It will already receive `btn btn-error`. + # * `onClick` (optional) {Function} callback to call when the button is + # clicked. The context will be set to the {NotificationElement} + # instance. + # * `text` {String} inner text for the button + # * `description` (optional) A {String} that will be rendered as Markdown + # to describe the notification. + # * `detail` (optional) A preformatted {String} that will be rendered as + # plain text with details about the notification. # * `dismissable` (optional) A {Boolean} indicating whether this # notification can be dismissed by the user. Defaults to `false`. # * `icon` (optional) A {String} name of an icon from Octicons to display # in the notification header. Defaults to `'flame'`. + # * `stack` (optional) A preformatted {String} with stack trace information + # describing the location of the error. addError: (message, options) -> @addNotification(new Notification('error', message, options)) @@ -85,12 +127,24 @@ class NotificationManager # # * `message` A {String} message # * `options` (optional) An options {Object} with the following keys: - # * `detail` (optional) A {String} with additional details about the - # notification. + # * `buttons` (optional) An {Array} of {Object} where each {Object} has the + # following options: + # * `className` (optional) {String} additional class name add to the + # button. It will already receive `btn btn-error`. + # * `onClick` (optional) {Function} callback to call when the button is + # clicked. The context will be set to the {NotificationElement} + # instance. + # * `text` {String} inner text for the button + # * `description` (optional) A {String} that will be rendered as Markdown + # to describe the notification. + # * `detail` (optional) A preformatted {String} that will be rendered as + # plain text with details about the notification. # * `dismissable` (optional) A {Boolean} indicating whether this # notification can be dismissed by the user. Defaults to `false`. # * `icon` (optional) A {String} name of an icon from Octicons to display # in the notification header. Defaults to `'bug'`. + # * `stack` (optional) A preformatted {String} with stack trace information + # describing the location of the error. addFatalError: (message, options) -> @addNotification(new Notification('fatal', message, options))