docs: clarify setting ID and display title rules (#7658)

Author: rzhao271

api/references/contribution-points.md

@@ -141,7 +141,7 @@ See the [Commands Extension Guide](https://code.visualstudio.com/api/extension-g
 
 ## contributes.configuration
 
-Contribute configuration keys that will be exposed to the user. The user will be able to set these configuration options in the Settings editor or by editing a settings.json file directly.
+Contribute settings that will be exposed to the user. The user will be able to set these configuration options in the Settings editor or by editing a settings.json file directly.
 
 This section can either be a single object, representing a single category of settings, or an array of objects, representing multiple categories of settings. If there are multiple categories of settings, the Settings editor will show a submenu in the table of contents for that extension, and the title keys will be used for the submenu entry names.
 
@@ -191,7 +191,7 @@ The `title` 1️⃣️ of a category is the heading used for that category.
 }
 ```
 
-Note that if the extension has multiple categories of extensions, and the title of one of the categories is the same as the extension display name, then the settings for that category will be placed directly below the main extension heading, no matter what the `order` field is set to.
+For an extension with multiple categories of settings, if the title of one of the categories is the same as the extension's display name, then the settings UI will treat that category as a "default category", ignoring the `order` field for that category and placing its settings below the main extension heading.
 
 For both the `title` and `displayName` fields, words like "Extension", "Configuration", and "Settings" are redundant.
 
@@ -202,32 +202,25 @@ For both the `title` and `displayName` fields, words like "Extension", "Configur
 
 #### properties
 
-The `properties` 2️⃣ in your configuration will be a dictionary of configuration properties.
+The `properties` 2️⃣ in your `configuration` object will form a dictionary where the keys are setting IDs and the values give more information on the setting. Though an extension can contain multiple categories of settings, each setting of the extension must still have its own unique ID. A setting ID cannot be a complete prefix of another setting ID.
 
-In the settings UI, your configuration key will be used to namespace and construct a title. Though an extension can contain multiple categories of settings, each setting of the extension must still have its own unique key. Capital letters in your key are used to indicate word breaks. For example, if your key is `gitMagic.blame.dateFormat`, the generated title for the setting will look like this:
+Properties without an explicit `order` field will appear in lexicographical order in the settings UI (**not** the order in which they're listed in the manifest).
 
-> Blame: **Date Format**
+### Setting titles
 
-Entries will be grouped according to the hierarchy established in your keys. So for example, these entries
+In the settings UI, multiple fields will be used to construct a display title for each setting. Capital letters in your key are used to indicate word breaks.
 
-```text
-gitMagic.blame.dateFormat
-gitMagic.blame.format
-gitMagic.blame.heatMap.enabled
-gitMagic.blame.heatMap.location
-```
+#### Display titles for single-category and default category configurations
+
+If the configuration has a single category of settings, or if the category has the same title as the extension's display name, then for settings within that category, the settings UI will use the settings ID and the extension `name` field to determine the display title.
+
+As an example, for settings ID `gitMagic.blame.dateFormat` and extension name `authorName.gitMagic`, because the prefix of the settings ID matches with the suffix of the extension name, the `gitMagic` part of the settings ID will be removed in the display title: "Blame: **Date Format**".
 
-will appear in a single group like this:
+#### Display titles for multi-category configurations
 
-> Blame: **Date Format**
->
-> Blame: **Format**
->
-> Blame › Heat Map: **Enabled**
->
-> Blame › Heat Map: **Location**
+If the configuration has multiple categories of settings, and the category does not have the same title as the extension's display name, then for settings within that category, the settings UI will use the settings ID and the category `id` field to determine the display title.
 
-Otherwise, properties without an explicit order field appear in alphabetical order (**not** the order in which they're listed in the manifest).
+As an example, for settings ID `css.completion.completePropertyWithSemicolon` and category ID `css`, because the prefix of the settings ID matches with the suffix of the category ID, the `css` part of the settings ID will be removed in the settings UI, and the generated title for the setting will be "Completion: **Complete Property With Semicolon**".
 
 ### Configuration property schema
 
@@ -246,7 +239,7 @@ Your `description` 3️⃣ appears after the title and before the input field, e
 }
 ```
 
-If you use `markdownDescription` instead of `description`, your setting description will be rendered as Markdown in the settings UI.
+If you use `markdownDescription` instead of `description`, your setting description will be parsed as Markdown in the settings UI.
 
 ```json
 {
@@ -274,7 +267,7 @@ Entries of type `number` 4️⃣ , `string` 5️⃣ , `boolean` 6️⃣ can be e
 
 A string setting can be rendered with a multiline text input if it sets `"editPresentation": "multilineText"` on the configuration entry.
 
-For `boolean` entries, the `description` (or `markdownDescription`) will be used as the label for the checkbox.
+For `boolean` entries, the `markdownDescription` (or `description` if `markdownDescription` is not specified) will be used as the label next to the checkbox.
 
 ```json
 {
@@ -297,7 +290,7 @@ If two categories have `order` properties, the category with the lower order num
 
 If two settings within the same category have `order` properties, the setting with the lower order number comes first. If another setting within that same category is not given an `order` property, it will appear after settings in that category that were given that property.
 
-If two categories have the same `order` property value, or if two settings within the same category have the same `order` property value, then they will be sorted in increasing alphabetical order within the settings UI.
+If two categories have the same `order` property value, or if two settings within the same category have the same `order` property value, then they will be sorted in increasing lexicographical order within the settings UI.
 
 #### enum / enumDescriptions / markdownEnumDescriptions / enumItemLabels