From d487556d4d46366cba4684ca933df6b9d6824201 Mon Sep 17 00:00:00 2001
From: Oleg Solomko <legomushroom@gmail.com>
Date: Sat, 1 Feb 2025 01:00:37 -0800
Subject: [PATCH] prompt files config description update (#239279)

* [config]: improve setting description and add examples

* [config]: fix localization ID compilation issue

* [config]: update the `Examples` header level to h4
---
 .../contrib/chat/browser/chat.contribution.ts | 11 ++---
 .../chat/common/promptSyntax/config.ts        | 45 ++++++++++++++++---
 2 files changed, 43 insertions(+), 13 deletions(-)

diff --git a/src/vs/workbench/contrib/chat/browser/chat.contribution.ts b/src/vs/workbench/contrib/chat/browser/chat.contribution.ts
index cf1d9b2ebf817..269b6536eab8b 100644
--- a/src/vs/workbench/contrib/chat/browser/chat.contribution.ts
+++ b/src/vs/workbench/contrib/chat/browser/chat.contribution.ts
@@ -154,14 +154,9 @@ configurationRegistry.registerConfiguration({
 			default: true
 		},
 		[PromptFilesConfig.CONFIG_KEY]: {
-			type: ['string', 'array', 'object', 'boolean', 'null'],
-			title: nls.localize('chat.promptFiles.setting.title', "Prompt Files"),
-			markdownDescription: nls.localize(
-				'chat.promptFiles.setting.markdownDescription',
-				"Enable support for attaching reusable prompt files (`*{0}`) for Chat, Edits, and Inline Chat sessions. [Learn More]({1}).",
-				'.prompt.md',
-				PromptFilesConfig.DOCUMENTATION_URL,
-			),
+			type: ['boolean', 'object', 'array', 'string', 'null'],
+			title: PromptFilesConfig.CONFIG_TITLE,
+			markdownDescription: PromptFilesConfig.CONFIG_DESCRIPTION,
 			default: null,
 			tags: ['experimental'],
 		},
diff --git a/src/vs/workbench/contrib/chat/common/promptSyntax/config.ts b/src/vs/workbench/contrib/chat/common/promptSyntax/config.ts
index 1fa52b8fea9b0..51eb7333f07a7 100644
--- a/src/vs/workbench/contrib/chat/common/promptSyntax/config.ts
+++ b/src/vs/workbench/contrib/chat/common/promptSyntax/config.ts
@@ -3,6 +3,8 @@
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
 
+import * as nls from '../../../../../nls.js';
+import { PROMPT_SNIPPET_FILE_EXTENSION } from './contentProviders/promptContentsProviderBase.js';
 import { IConfigurationService } from '../../../../../platform/configuration/common/configuration.js';
 
 /**
@@ -21,21 +23,21 @@ import { IConfigurationService } from '../../../../../platform/configuration/com
  * (see {@link DEFAULT_LOCATION}):
  * ```json
  * {
- *   "chat.experimental.promptSnippets": true,
+ *   "chat.promptFiles": true,
  * }
  * ```
  *
  * Enable the feature, specifying a single prompt files source folder location:
  * ```json
  * {
- *   "chat.experimental.promptSnippets": '.github/prompts',
+ *   "chat.promptFiles": '.github/prompts',
  * }
  * ```
  *
  * Enable the feature, specifying multiple prompt files source folder location:
  * ```json
  * {
- *   "chat.experimental.promptSnippets": {
+ *   "chat.promptFiles": {
  *     ".github/prompts" : true,
  *     ".copilot/prompts" : false,
  *     "/Users/legomushroom/repos/prompts" : true,
@@ -46,7 +48,7 @@ import { IConfigurationService } from '../../../../../platform/configuration/com
  * Enable the feature, specifying multiple prompt files source folder location:
  * ```json
  * {
- *   "chat.experimental.promptSnippets": [
+ *   "chat.promptFiles": [
  *     ".github/prompts",
  *     ".copilot/prompts",
  *     "/Users/legomushroom/repos/prompts",
@@ -64,7 +66,7 @@ import { IConfigurationService } from '../../../../../platform/configuration/com
  * (see {@link DEFAULT_LOCATION}):
  * ```json
  * {
- *   "chat.experimental.promptSnippets": {},
+ *   "chat.promptFiles": {},
  * }
  * ```
  *
@@ -213,6 +215,39 @@ export namespace PromptFilesConfig {
 
 		return DEFAULT_LOCATION;
 	};
+
+	const usageExample1 = nls.localize(
+		`chat.promptFiles.config.description.example1`,
+		"Enable with the default location of the prompt files (`{0}`):\n{1}",
+		DEFAULT_LOCATION[0],
+		`\`\`\`json\n{\n  "${CONFIG_KEY}": true,\n}\n\`\`\``,
+	);
+	const usageExample2 = nls.localize(
+		`chat.promptFiles.config.description.example2`,
+		"Specify custom location(s) of the prompt files:\n{0}",
+		`\`\`\`json\n{\n  "${CONFIG_KEY}": {\n    ".github/prompts": true,\n    "/Users/vscode/prompts": true,\n}\n\`\`\``,
+	);
+
+	/**
+	 * Configuration setting description to use in the settings UI.
+	 */
+	export const CONFIG_DESCRIPTION = nls.localize(
+		'chat.promptFiles.config.description',
+		"Enable support for attaching reusable prompt files (`*{0}`) for Chat, Edits, and Inline Chat sessions. [Learn More]({1}).\n\nSet to `true` or use the `{ \"/path/to/folder\": boolean }` notation to specify a different path (or a couple of them). Relative paths are resolved from the root folder(s) of your workspace, and the default value of `{2}` is used if no other paths provided.\n#### Examples\n{3}\n{4}",
+		PROMPT_SNIPPET_FILE_EXTENSION,
+		DOCUMENTATION_URL,
+		DEFAULT_LOCATION[0],
+		usageExample1,
+		usageExample2,
+	);
+
+	/**
+	 * Configuration setting title to use in the settings UI.
+	 */
+	export const CONFIG_TITLE = nls.localize(
+		`chat.promptFiles.config.title`,
+		"Prompt Files",
+	);
 }
 
 /**