From 021b5ab7532399272334e40d5783962e70bfa71a Mon Sep 17 00:00:00 2001
From: Benjamin Pasero <benjpas@microsoft.com>
Date: Mon, 1 Jul 2019 08:07:39 +0200
Subject: [PATCH] web api docs

---
 .../services/userData/common/userData.ts      | 47 +++++++++++++++++++
 src/vs/workbench/workbench.web.api.ts         |  4 ++
 2 files changed, 51 insertions(+)

diff --git a/src/vs/workbench/services/userData/common/userData.ts b/src/vs/workbench/services/userData/common/userData.ts
index de051b0ec5d..dc448d2c9c5 100644
--- a/src/vs/workbench/services/userData/common/userData.ts
+++ b/src/vs/workbench/services/userData/common/userData.ts
@@ -5,13 +5,60 @@
 
 import { Event } from 'vs/base/common/event';
 
+/**
+ * The userDataProvider is used to handle user specific application
+ * state like settings, keybindings, UI state (e.g. opened editors) and snippets.
+ *
+ * The API reflects a simple file system provider that comes with the notion of paths
+ * (UNIX slash separated) as well as files. Folders are not a top level concept (e.g. we
+ * do not require to create or delete them), however, files can be grouped beneath one path
+ * and also listed from that path.
+ *
+ * Example:
+ * ```ts
+ * await writeFile('snippets/global/markdown.json', <some data>);
+ * await writeFile('snippets/global/html.json', <some data>);
+ * await writeFile('snippets/global/javascript.json', <some data>);
+ *
+ * const files = await listFiles('snippets/global');
+ * console.log(files); // -> ['snippets/global/markdown.json', 'snippets/global/html.json', 'snippets/global/javascript.json']
+ * ```
+ */
 export interface IUserDataProvider {
 
+	/**
+	 * Emitted when one ore more files are added, changed or deleted. The event provides
+	 * an array of paths of these files.
+	 */
 	readonly onDidChangeFile: Event<string[]>;
 
+	/**
+	 * Read the file contents of the given path.
+	 *
+	 * Throw an error if the path does not exist.
+	 */
 	readFile(path: string): Promise<Uint8Array>;
+
+	/**
+	 * Writes the provided content to the file path overwriting any existing content on that path.
+	 *
+	 * If the path does not exist, it will be created.
+	 *
+	 * Throw an error if the path is a parent to existing files.
+	 */
 	writeFile(path: string, content: Uint8Array): Promise<void>;
+
+	/**
+	 * Delete the file at the given path.
+	 *
+	 * Does NOT throw an error when the path does not exist.
+	 */
 	deleteFile(path: string): Promise<void>;
 
+	/**
+	 * Returns an array of files at the given path.
+	 *
+	 * Throw an error if the path does not exist or points to a file.
+	 */
 	listFiles(path: string): Promise<string[]>;
 }
\ No newline at end of file
diff --git a/src/vs/workbench/workbench.web.api.ts b/src/vs/workbench/workbench.web.api.ts
index 4c09e78e7c3..cfaa8103f76 100644
--- a/src/vs/workbench/workbench.web.api.ts
+++ b/src/vs/workbench/workbench.web.api.ts
@@ -32,6 +32,10 @@ export interface IWorkbenchConstructionOptions {
 	 */
 	workspaceUri?: UriComponents;
 
+	/**
+	 * Experimental: The userDataProvider is used to handle user specific application
+	 * state like settings, keybindings, UI state (e.g. opened editors) and snippets.
+	 */
 	userDataProvider?: IUserDataProvider;
 }
 
-- 
GitLab