doc on launch/tasks.json files, #12813

src/vs/vscode.d.ts

@@ -2649,9 +2649,24 @@ declare namespace vscode {
 	}
 
 	/**
-	 * Represents the workspace configuration. The workspace configuration
-	 * is always a merged view of the configuration of the current [workspace](#workspace.rootPath)
-	 * and the installation-wide configuration.
+	 * Represents the workspace configuration.
+	 *
+	 * The workspace configuration is a merged view: Configurations of the current [workspace](#workspace.rootPath)
+	 * (if available), files like `launch.json`, and the installation-wide configuration. Workspace specific values
+	 * shadow installation-wide values.
+	 *
+	 * *Note:* The merged configuration of the current [workspace](#workspace.rootPath)
+	 * also contains settings from files like `launch.json` and `tasks.json`. Their basename will be
+	 * part of the section identifier. The following snippets shows how to retrieve all configurations
+	 * from `launch.json`:
+	 *
+	 * ```
+	 *	// launch.json configuration
+	 * 	const config = workspace.getConfiguration('launch');
+	 *
+	 * // retrieve values
+	 * 	cont values = config.get('configurations')
+	 *```
 	 */
 	export interface WorkspaceConfiguration {
 
@@ -2674,9 +2689,13 @@ declare namespace vscode {
 
 		/**
 		 * Update a configuration value. A value can be changed for the current
-		 * [workspace](#workspace.rootPath) only or globally for all instances of the
+		 * [workspace](#workspace.rootPath) only, or globally for all instances of the
 		 * editor. The updated configuration values are persisted.
 		 *
+		 * *Note:* Setting an installation-wide value (`global: true`) in the presence of
+		 * a more specific workspace value has no observable effect in that workspace, but
+		 * in others.
+		 *
 		 * @param section Configuration name, supports _dotted_ names.
 		 * @param value The new value.
 		 * @param global When `true` changes the configuration value for all instances of the editor.