notifications - add some API docs

src/vs/platform/dialogs/common/dialogs.ts

@@ -33,18 +33,24 @@ export interface IConfirmationService {
 	_serviceBrand: any;
 
 	/**
-	 * Ask the user for confirmation.
+	 * Ask the user for confirmation with a modal dialog.
 	 */
 	confirm(confirmation: IConfirmation): TPromise<boolean>;
 
 	/**
-	 * Ask the user for confirmation with a checkbox.
+	 * Ask the user for confirmation with a checkbox in a modal dialog.
 	 */
 	confirmWithCheckbox(confirmation: IConfirmation): TPromise<IConfirmationResult>;
 }
 
 export const IChoiceService = createDecorator<IChoiceService>('choiceService');
 
+/**
+ * The choices to present to the user. The `isSecondary` hint allows to control where
+ * choices appear when the `modal` option is set to `false`. In that case, the choices
+ * are presented as part of a notification and secondary choices will appear less
+ * prominent.
+ */
 export type Choice = string | { label: string; isSecondary?: boolean; };
 
 export interface IChoiceService {
@@ -54,6 +60,11 @@ export interface IChoiceService {
 	/**
 	 * Prompt the user for a choice between multiple choices.
 	 *
+	 * @param choices the choices to present to the user. The `isSecondary` hint allows
+	 * to control where are presented as part of a notification and secondary choices will
+	 * appear less choices appear when the `modal` option is set to `false`. In that case,
+	 * the choices prominent.
+	 *
 	 * @param when `modal` is true, this will block the user until chooses.
 	 *
 	 * @returns A promise with the selected choice index. The promise is cancellable

src/vs/platform/notification/common/notification.ts

@@ -19,30 +19,108 @@ export const INotificationService = createDecorator<INotificationService>('notif
 export type NotificationMessage = string | IMarkdownString | Error;
 
 export interface INotification {
+
+	/**
+	 * The severity of the notification. Either `Info`, `Warning` or `Error`.
+	 */
 	severity: Severity;
+
+	/**
+	 * The message of the notification. This can either be a `string`, `Error`
+	 * or `IMarkdownString`.
+	 *
+	 * **Note:** Currently only links are supported in notifications. Links to commands can
+	 * be embedded provided that the `IMarkdownString` is trusted.
+	 */
 	message: NotificationMessage;
+
+	/**
+	 * The source of the notification appears as additional information.
+	 */
 	source?: string;
+
+	/**
+	 * Actions to show as part of the notification. Primary actions show up as
+	 * buttons as part of the message and will close the notification once clicked.
+	 *
+	 * Secondary actions are meant to provide additional configuration or context
+	 * for the notification and will show up less prominent. A notification does not
+	 * close automatically when invoking a secondary action.
+	 *
+	 * **Note:** If your intent is to show a message with actions to the user, consider
+	 * the `IChoiceService` and `IConfirmationService` instead which are optimized for
+	 * this usecase and much easier to use!
+	 */
 	actions?: INotificationActions;
 }
 
 export interface INotificationActions {
+
+	/**
+	 * Primary actions show up as buttons as part of the message and will close
+	 * the notification once clicked.
+	 */
 	primary?: IAction[];
+
+	/**
+	 * Secondary actions are meant to provide additional configuration or context
+	 * for the notification and will show up less prominent. A notification does not
+	 * close automatically when invoking a secondary action.
+	 */
 	secondary?: IAction[];
 }
 
 export interface INotificationProgress {
+
+	/**
+	 * Causes the progress bar to spin infinitley.
+	 */
 	infinite(): void;
+
+	/**
+	 * Indicate the total amount of work.
+	 */
 	total(value: number): void;
+
+	/**
+	 * Indicate that a specific chunk of work is done.
+	 */
 	worked(value: number): void;
+
+	/**
+	 * Indicate that the long running operation is done.
+	 */
 	done(): void;
 }
 
 export interface INotificationHandle extends IDisposable {
+
+	/**
+	 * Will be fired once the notification hides.
+	 */
 	readonly onDidHide: Event<void>;
+
+	/**
+	 * Allows to indicate progress on the notification even after the
+	 * notification is already visible.
+	 */
 	readonly progress: INotificationProgress;
 
+	/**
+	 * Allows to update the severity of the notification.
+	 */
 	updateSeverity(severity: Severity): void;
+
+	/**
+	 * Allows to update the message of the notification even after the
+	 * notification is already visible.
+	 */
 	updateMessage(message: NotificationMessage): void;
+
+	/**
+	 * Allows to update the actions of the notification even after the
+	 * notification is already visible.
+	 */
 	updateActions(actions?: INotificationActions): void;
 }
 
@@ -50,10 +128,32 @@ export interface INotificationService {
 
 	_serviceBrand: any;
 
+	/**
+	 * Show the provided notification to the user. The returned `INotificationHandle`
+	 * can be used to control the notification afterwards.
+	 *
+	 * **Note:** If your intent is to show a message with actions to the user, consider
+	 * the `IChoiceService` and `IConfirmationService` instead which are optimized for
+	 * this usecase and much easier to use!
+	 */
 	notify(notification: INotification): INotificationHandle;
 
+	/**
+	 * A convinient way of reporting infos. Use the `INotificationService.notify`
+	 * method if you need more control over the notification.
+	 */
 	info(message: NotificationMessage | NotificationMessage[]): void;
+
+	/**
+	 * A convinient way of reporting warnings. Use the `INotificationService.notify`
+	 * method if you need more control over the notification.
+	 */
 	warn(message: NotificationMessage | NotificationMessage[]): void;
+
+	/**
+	 * A convinient way of reporting errors. Use the `INotificationService.notify`
+	 * method if you need more control over the notification.
+	 */
 	error(message: NotificationMessage | NotificationMessage[]): void;
 }