diff --git a/README.md b/README.md index 882e076d..6b23bf80 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,8 @@ This VS Code extension provides support for creating and editing XML documents, * [Minify XML](https://github.com/redhat-developer/vscode-xml/blob/main/docs/Commands.md#minify-xml-document) * [Generate XML from Grammar](https://github.com/redhat-developer/vscode-xml/blob/main/docs/GenerateXMLFromGrammar.md#generate-xml-from-grammar) * [Generate Schema from XML](https://github.com/redhat-developer/vscode-xml/blob/main/docs/BindingWithGrammar.md#binding-with-new-grammar) + * *[Code Lens](https://github.com/redhat-developer/vscode-xml/blob/main/docs/CodeLens.md) when `xml.codeLens.enabled` is enabled* + * *[Inlay Hints](https://github.com/redhat-developer/vscode-xml/blob/main/docs/InlayHint.md) when `xml.inlayHint.enabled` is enabled* See the [changelog](CHANGELOG.md) for the latest release. @@ -100,6 +102,7 @@ The following settings are supported: * `xml.autoCloseTags.enabled` : Enable/disable autoclosing of XML tags. Default is `true`. **IMPORTANT**: The following settings must be turned of for this to work: `editor.autoClosingTags`, `editor.autoClosingBrackets`. * [`xml.codeLens.enabled`](https://github.com/redhat-developer/vscode-xml/blob/main/docs/CodeLens.md): Enable/disable XML CodeLens. Default is `false`. +* [`xml.inlayHint.enabled`](https://github.com/redhat-developer/vscode-xml/blob/main/docs/InlayHint.md): Enable/disable XML Inlay Hints (default values, attribute types, element types). Default is `false`. * [`xml.preferences.showSchemaDocumentationType`](https://github.com/redhat-developer/vscode-xml/blob/main/docs/Preferences.md#documentation-type): Specifies the source of the XML schema documentation displayed on hover and completion. Default is `all`. * [`xml.validation.enabled`](https://github.com/redhat-developer/vscode-xml/blob/main/docs/Validation.md): Enable/disable all validation. Default is `true`. * [`xml.validation.namespaces.enabled`](https://github.com/redhat-developer/vscode-xml/blob/main/docs/Validation.md#xmlvalidationsnamespacesenabled): Enable/disable namespaces validation. Default is `always`. Ignored if [`xml.validation.enabled`](https://github.com/redhat-developer/vscode-xml/blob/main/docs/Validation.md) is set to `false`. diff --git a/docs/InlayHint.md b/docs/InlayHint.md new file mode 100644 index 00000000..50c46efb --- /dev/null +++ b/docs/InlayHint.md @@ -0,0 +1,123 @@ + +## Inlay Hint + +Inlay hints display grammar-derived information directly in the editor to help you understand the structure of your XML documents without having to look at the schema. + +To enable inlay hints, set `xml.inlayHint.enabled` to `true` (default is `false`). + +There are three kinds of inlay hints, each controlled by its own setting: + +| Setting | Default | Description | +|---------|---------|-------------| +| `xml.inlayHint.enabled` | `false` | Enable/disable XML inlay hints | +| `xml.inlayHint.showDefaultValue` | `true` | Show default attribute values from the grammar | +| `xml.inlayHint.showAttributeType` | `true` | Show attribute types (e.g., `: xs:integer`) | +| `xml.inlayHint.showElementType` | `true` | Show element types (e.g., `: xs:boolean`) | + +Types equal to `xs:string` are automatically filtered out as they are too common to be informative. + +### Default attribute values + +When an XML file is bound to a grammar (XSD, DTD) that defines `default` or `fixed` attribute values, inlay hints show these values next to the element's start tag for attributes that are not explicitly set. + +For example, given the following XSD (`form.xsd`): + +```xml + + + + + + + + + + + + + + + + + + + + +``` + +And the following XML (`form.xml`): + +```xml + +
+ + +
+``` + +Inlay hints for default attribute values will appear: + +- On `
`: `lang="en"`, `method="GET"`, `debug="false"` +- On ``: `type="text"`, `required="false"` +- On ``: `type="text"` (but not `required` since it is explicitly set) + +![XSD default attribute value inlay hints](./images/InlayHint/InlayHintDefaultValueXSD.png) + +Default attribute values defined in DTD `ATTLIST` declarations are also shown. + +Given the following DTD (`note.dtd`): + +```dtd + + +``` + +And the following XML (`note.xml`): + +```xml + + +Remember to review the inlay hint PR. +``` + +Inlay hints `status="draft"` and `priority="normal"` will appear after the `note` tag name. + +![DTD default attribute value inlay hints](./images/InlayHint/InlayHintDefaultValueDTD.png) + +### Attribute types + +When enabled, attribute type hints show the XSD type of each attribute after the attribute name (before the `=` sign). + +Using the same `form.xsd` and `form.xml` above, the following attribute type hints are shown: + +- `maxRetries` → `: xs:int` +- `maxLength` → `: xs:integer` +- `required` → `: xs:boolean` +- `lang`, `method`, `name`, `type` → no type hint (`xs:string` is filtered out) + +![Attribute type inlay hints](./images/InlayHint/InlayHintAttributeType.png) + +### Element types + +When enabled, element type hints show the XSD type of each element after the element tag name. + +Using the same `form.xsd` and `form.xml` above, the following element type hints are shown: + +- `` → `: inputType` +- `` → no type hint (anonymous complex type, no named type) + +![Element type inlay hints](./images/InlayHint/InlayHintElementType.png) + +Elements with anonymous (inline) complex types do not show a type hint, since they have no named type. + +### Settings + +- `xml.inlayHint.enabled`: Enable/disable XML inlay hints. Default is `false`. +- `xml.inlayHint.showDefaultValue`: Show default attribute values from grammar. Default is `true`. +- `xml.inlayHint.showAttributeType`: Show attribute types. Default is `true`. +- `xml.inlayHint.showElementType`: Show element types. Default is `true`. diff --git a/docs/Preferences.md b/docs/Preferences.md index e08c0501..594e866a 100644 --- a/docs/Preferences.md +++ b/docs/Preferences.md @@ -136,6 +136,10 @@ See the [Formatting page](Formatting.md#formatting). Use `xml.codeLens.enabled` in order to enable or disable code lens. Please see [the Code Lens page](CodeLens.md#code-lens) for more information. +## Inlay Hint + +Use `xml.inlayHint.enabled` to enable inlay hints (default is `false`). Once enabled, use `xml.inlayHint.showDefaultValue`, `xml.inlayHint.showAttributeType`, and `xml.inlayHint.showElementType` to control individual inlay hint features. Please see [the Inlay Hint page](InlayHint.md#inlay-hint) for more information. + ## Tag Auto Closing The closing tags for elements should automatically be added when typing `>` to complete an opening tag. diff --git a/docs/images/InlayHint/InlayHintAttributeType.png b/docs/images/InlayHint/InlayHintAttributeType.png new file mode 100644 index 00000000..6988e5df Binary files /dev/null and b/docs/images/InlayHint/InlayHintAttributeType.png differ diff --git a/docs/images/InlayHint/InlayHintDefaultValueDTD.png b/docs/images/InlayHint/InlayHintDefaultValueDTD.png new file mode 100644 index 00000000..3db865fb Binary files /dev/null and b/docs/images/InlayHint/InlayHintDefaultValueDTD.png differ diff --git a/docs/images/InlayHint/InlayHintDefaultValueXSD.png b/docs/images/InlayHint/InlayHintDefaultValueXSD.png new file mode 100644 index 00000000..293c02de Binary files /dev/null and b/docs/images/InlayHint/InlayHintDefaultValueXSD.png differ diff --git a/docs/images/InlayHint/InlayHintElementType.png b/docs/images/InlayHint/InlayHintElementType.png new file mode 100644 index 00000000..31ca78bb Binary files /dev/null and b/docs/images/InlayHint/InlayHintElementType.png differ diff --git a/package.json b/package.json index b0193872..0d7629b9 100644 --- a/package.json +++ b/package.json @@ -709,6 +709,26 @@ "default": false, "markdownDescription": "Enable/disable XML CodeLens. Default is `false`. See [here](command:xml.open.docs?%5B%7B%22page%22%3A%22CodeLens%22%2C%22section%22%3A%22Code%20Lens%22%7D%5D) for information about CodeLens features" }, + "xml.inlayHint.enabled": { + "type": "boolean", + "default": false, + "markdownDescription": "Enable/disable XML inlay hints. Default is `false`. See [here](command:xml.open.docs?%5B%7B%22page%22%3A%22InlayHint%22%2C%22section%22%3A%22Inlay%20Hint%22%7D%5D) for more information." + }, + "xml.inlayHint.showDefaultValue": { + "type": "boolean", + "default": true, + "markdownDescription": "Show default attribute values defined by the grammar (XSD, DTD) as inlay hints. Default is `true`. See [here](command:xml.open.docs?%5B%7B%22page%22%3A%22InlayHint%22%2C%22section%22%3A%22Inlay%20Hint%22%7D%5D) for more information." + }, + "xml.inlayHint.showAttributeType": { + "type": "boolean", + "default": true, + "markdownDescription": "Show the type of XML attributes (e.g., `: xs:integer`) as inlay hints after the attribute name. Types equal to `xs:string` are filtered out. Default is `true`. See [here](command:xml.open.docs?%5B%7B%22page%22%3A%22InlayHint%22%2C%22section%22%3A%22Inlay%20Hint%22%7D%5D) for more information." + }, + "xml.inlayHint.showElementType": { + "type": "boolean", + "default": true, + "markdownDescription": "Show the type of XML elements (e.g., `: xs:integer`) as inlay hints before the closing `>` of the start tag. Types equal to `xs:string` are filtered out. Default is `true`. See [here](command:xml.open.docs?%5B%7B%22page%22%3A%22InlayHint%22%2C%22section%22%3A%22Inlay%20Hint%22%7D%5D) for more information." + }, "xml.semanticTokens.enabled": { "type": "boolean", "default": true,