From 68c0f0a9d8cd307fca332a8ff3b364bb93a03c07 Mon Sep 17 00:00:00 2001 From: Patrick Scheibe Date: Mon, 22 May 2023 12:59:11 +0200 Subject: [PATCH] Add parentheses to methods and remove usage of "you" --- .../custom_language_support/websymbols.md | 4 +-- .../websymbols_implementation.md | 27 +++++++------- .../websymbols_integration.md | 36 +++++++++---------- .../websymbols_web_types.md | 4 +-- 4 files changed, 37 insertions(+), 34 deletions(-) diff --git a/topics/reference_guide/custom_language_support/websymbols.md b/topics/reference_guide/custom_language_support/websymbols.md index 9380613f0..f239c6804 100644 --- a/topics/reference_guide/custom_language_support/websymbols.md +++ b/topics/reference_guide/custom_language_support/websymbols.md @@ -36,7 +36,7 @@ Currently, IDEs provide built-in integration for following language features (se There's also the option to write integration for other languages. -In the following sub-pages you learn about implementing Web Symbols for your plugin and how you can -contribute Web Symbols by statically defining them through JSON schemas: +The following sub-pages provide information on how to implement Web Symbols for plugins and how to +define them statically through JSON schemas: - [](websymbols_implementation.md) - [](websymbols_web_types.md) diff --git a/topics/reference_guide/custom_language_support/websymbols_implementation.md b/topics/reference_guide/custom_language_support/websymbols_implementation.md index 9f4491d95..fcb127d6d 100644 --- a/topics/reference_guide/custom_language_support/websymbols_implementation.md +++ b/topics/reference_guide/custom_language_support/websymbols_implementation.md @@ -8,12 +8,13 @@ Implementation details for the Web Symbols API. The core element of the framework is a [`WebSymbol`](%gh-ic%/platform/webSymbols/src/com/intellij/webSymbols/WebSymbol.kt), -which represents an entity in the Web Symbols model. -It is described through `namespace`, `kind` and `name` properties. Its lifecycle is a single read action. -If you need it to survive between read actions, use `WebSymbol.createPointer()` to create a symbol pointer. -If the symbol is still valid, dereferencing the pointer will return a new instance of the symbol. -During write action, the symbol might not survive PSI tree commit, so you should create a pointer -before the commit and dereference it afterward. +representing an entity in the Web Symbols model. +This symbol is characterized by `namespace`, `kind` and `name` properties, with its lifecycle encapsulated +within a single read action. +To ensure its survival between read actions, use `WebSymbol.createPointer()` to create a symbol pointer. +Provided the symbol remains valid, dereferencing the pointer will return a new instance of the symbol. +It should be noted that during a write action, the symbol might not survive a PSI tree commit. +Therefore, creating a pointer prior to the commit and dereferencing it post-commit is advised. The property `namespace` describes which language or concept (not tied to a particular language) the symbol belongs to, and `kind` describes which group of symbols within that particular language or concept it belongs to. @@ -223,8 +224,9 @@ A symbol should implement [`PsiSourcedWebSymbol`](%gh-ic%/platform/webSymbols/src/com/intellij/webSymbols/PsiSourcedWebSymbol.kt) if its declaration is a regular `PsiElement`, e.g. a variable or a declared type. Once a symbol implements this interface it can be searched and refactored together with the PSI element declaration. -If your symbol is part of a `PsiElement` (e.g. part of a string literal), or spans multiple PSI elements, or does not relate 1-1 with a PSI element, -instead of implementing this interface you should contribute dedicated declaration provider. +In case a symbol is part of a `PsiElement` (for instance, being part of a string literal), +spans multiple PSI elements, or does not correlate one-to-one with a PSI element, +contribution of a dedicated declaration provider instead of implementing this interface is recommended. ### Properties {#psisourcedwebsymbol-properties} @@ -279,10 +281,11 @@ getModificationCount() : Symbol scopes are used in CachedValues as dependencies for query executors. If a symbol scope instance can mutate over the time, it should properly implement this method. -When implementing a scope, which contains many elements you should extend -[`WebSymbolsScopeWithCache`](%gh-ic%/platform/webSymbols/src/com/intellij/webSymbols/WebSymbolsScopeWithCache.kt), -which cache the list of symbols and uses efficient cache to speed up queries. -When extending the class, you only need to override the `initialize` method and provide parameters to the super constructor to specify how results should be cached. +When implementing a scope containing many elements, extension of +[`WebSymbolsScopeWithCache`](%gh-ic%/platform/webSymbols/src/com/intellij/webSymbols/WebSymbolsScopeWithCache.kt) is advised. +This structure caches the list of symbols and employs an efficient cache mechanism to speed up queries. +On extension of this class, it's only necessary to override `initialize()` and provide parameters to +the super constructor to specify the caching strategy for the results. ## Model Queries diff --git a/topics/reference_guide/custom_language_support/websymbols_integration.md b/topics/reference_guide/custom_language_support/websymbols_integration.md index 8624ec6b0..601efff0e 100644 --- a/topics/reference_guide/custom_language_support/websymbols_integration.md +++ b/topics/reference_guide/custom_language_support/websymbols_integration.md @@ -7,11 +7,10 @@ How to integrate your Web Symbols with a particular language feature. IDEs provide built-in support for Web Symbols integration with main language features of HTML, CSS and JavaScript. -You can contribute static symbols through Web Types or Custom Elements Manifest, or you can -create and register [`WebSymbolsQueryConfigurator`](%gh-ic%/platform/webSymbols/src/com/intellij/webSymbols/query/WebSymbolsQueryConfigurator.kt) -extension. +Contribution of static symbols can be achieved through Web Types or Custom Elements Manifest, +or by creating and registering a [`WebSymbolsQueryConfigurator`](%gh-ic%/platform/webSymbols/src/com/intellij/webSymbols/query/WebSymbolsQueryConfigurator.kt) extension. -The implementation of [`WebSymbolsQueryConfigurator`](%gh-ic%/platform/webSymbols/src/com/intellij/webSymbols/query/WebSymbolsQueryConfigurator.kt) requires overriding the `getScope` method. +The implementation of [`WebSymbolsQueryConfigurator`](%gh-ic%/platform/webSymbols/src/com/intellij/webSymbols/query/WebSymbolsQueryConfigurator.kt) requires overriding `getScope()`. This process involves the creation of a list of `WebSymbolScope`s, depending on the provided `PsiElement` (`element` parameter) and `WebSymbolContext` (`context` parameter). The following list of supported language features outlines the types of `PsiElement`s that can be expected @@ -32,7 +31,7 @@ HTML element symbols can be contributed statically or dynamically (through [`WebSymbolsQueryConfigurator`](%gh-ic%/platform/webSymbols/src/com/intellij/webSymbols/query/WebSymbolsQueryConfigurator.kt)). The statically contributed symbols are available globally, depending on the context setting of the contributing Web Types file. -For dynamic contributions the `WebSymbolsQueryConfigurator.getScope`'s `element` parameter can be: +For dynamic contributions the `WebSymbolsQueryConfigurator.getScope()`'s `element` parameter can be: - [`HtmlTag`](%gh-ic%/xml/xml-psi-api/src/com/intellij/psi/html/HtmlTag.java) - Web Symbols should represent available HTML elements. The HTML tag actual name should not be taken into account when building the scope. - `CssElement` - Web Symbols should represent available HTML elements within a particular CSS file. @@ -49,7 +48,7 @@ HTML attribute symbols can be contributed statically or dynamically (through [`W The statically contributed symbols are available globally, depending on the context setting of the contributing Web Types file. If the containing tag is matched to a Web Symbol it is added to the scope for attribute matching. -For dynamic contributions the `WebSymbolsQueryConfigurator.getScope`'s `element` parameter can be: +For dynamic contributions the `WebSymbolsQueryConfigurator.getScope()`'s `element` parameter can be: - [`XmlAttribute`](%gh-ic%/xml/xml-psi-api/src/com/intellij/psi/xml/XmlAttribute.java) - Web Symbols should represent available HTML attributes for matching. The HTML attribute actual name should not be taken into account when building the scope, however the parent HTML tag and other attributes can be taken into account when building the scope. - [`HtmlTag`](%gh-ic%/xml/xml-psi-api/src/com/intellij/psi/html/HtmlTag.java) - Web Symbols should represent available HTML attributes for matching. The HTML tag and other attributes can be taken into account when building the scope. @@ -77,7 +76,7 @@ Within an HTML element `style` attribute value, the additional scope is built fr Scope for custom properties (variables) references (arguments for [`var()`](https://developer.mozilla.org/en-US/docs/Web/CSS/var) function) is built the same way as for properties. Only properties with names starting with `--` are taken into account. -For dynamic contributions the `WebSymbolsQueryConfigurator.getScope`'s `element` parameter can be: +For dynamic contributions the `WebSymbolsQueryConfigurator.getScope()`'s `element` parameter can be: - `CssDeclaration` - Web Symbols should represent available CSS properties for matching. The CSS declaration actual name should not be taken into account when building the scope. #### Pseudo-elements {#css-pseudo-elements} @@ -93,7 +92,7 @@ The statically contributed symbols are available globally, depending on the cont The additional scope for matching pseudo-elements is built from Web Symbols matching HTML element name preceding the pseudo-element keyword. -For dynamic contributions the `WebSymbolsQueryConfigurator.getScope`'s `element` parameter can be: +For dynamic contributions the `WebSymbolsQueryConfigurator.getScope()`'s `element` parameter can be: - `CssPseudoSelector` - Web Symbols should represent available CSS pseudo-elements for matching. The CSS pseudo-element actual name should not be taken into account when building the scope. Dedicated support for `WebSymbol` interface properties: @@ -112,7 +111,7 @@ The statically contributed symbols are available globally, depending on the cont The additional scope for matching pseudo-classes is built from Web Symbols matching HTML element name preceding the pseudo-class keyword. -For dynamic contributions the `WebSymbolsQueryConfigurator.getScope`'s `element` parameter can be: +For dynamic contributions the `WebSymbolsQueryConfigurator.getScope()`'s `element` parameter can be: - `CssPseudoSelector` - Web Symbols should represent available CSS pseudo-classes for matching. The CSS pseudo-class actual name should not be taken into account when building the scope. Dedicated support for `WebSymbol` interface properties: @@ -130,7 +129,7 @@ The statically contributed symbols are available globally, depending on the cont The additional scope for matching functions is built from Web Symbols matching the CSS property name, the value of which is being calculated. -For dynamic contributions the `WebSymbolsQueryConfigurator.getScope`'s `element` parameter can be: +For dynamic contributions the `WebSymbolsQueryConfigurator.getScope()`'s `element` parameter can be: - `CssFunction` - Web Symbols should represent available CSS functions for matching. The CSS function actual name should not be taken into account when building the scope. #### Classes {#css-classes} @@ -148,7 +147,7 @@ Within CSS file the additional scope for matching classes is built from Web Symb Within HTML attribute `class` the additional scope for matching classes is built from Web Symbols matching the enclosing HTML element name. -For dynamic contributions the `WebSymbolsQueryConfigurator.getScope`'s `element` parameter can be: +For dynamic contributions the `WebSymbolsQueryConfigurator.getScope()`'s `element` parameter can be: - `CssClass` - Web Symbols should represent available CSS classes for matching. The CSS class actual name should not be taken into account when building the scope. - [`XmlAttributeValue`](%gh-ic%/xml/xml-psi-api/src/com/intellij/psi/xml/XmlAttributeValue.java) - Web Symbols should represent available CSS classes for matching within the attribute value. @@ -166,7 +165,7 @@ The statically contributed symbols are available globally, depending on the cont Within CSS file the additional scope for matching classes is built from Web Symbols matching HTML element name preceding the `::part` keyword. -For dynamic contributions the `WebSymbolsQueryConfigurator.getScope`'s `element` parameter can be: +For dynamic contributions the `WebSymbolsQueryConfigurator.getScope()`'s `element` parameter can be: - `CssTermImpl` - Web Symbols should represent available CSS parts for matching. The CSS part actual name should not be taken into account when building the scope. @@ -182,7 +181,7 @@ _2023.2+_ Web Symbols representing JavaScript or TypeScript string literals available in a particular location. Only dynamically contributed string literal symbols (through [`WebSymbolsQueryConfigurator`](%gh-ic%/platform/webSymbols/src/com/intellij/webSymbols/query/WebSymbolsQueryConfigurator.kt)) have built-in support. -The `WebSymbolsQueryConfigurator.getScope`'s `element` parameter can be: +The `WebSymbolsQueryConfigurator.getScope()`'s `element` parameter can be: - a `JSLiteralExpression` - an unqualified `JSReferenceExpression`, which parent is *not* `JSIndexedPropertyAccessExpression`, `JSCallExpression` or `JSProperty` @@ -197,7 +196,7 @@ _2023.2+_ Web Symbols representing properties of an object, which is a result of a JavaScript or TypeScript expression. Only dynamically contributed properties symbols (through [`WebSymbolsQueryConfigurator`](%gh-ic%/platform/webSymbols/src/com/intellij/webSymbols/query/WebSymbolsQueryConfigurator.kt)) have built-in support. -The `WebSymbolsQueryConfigurator.getScope`'s `element` parameter can be: +The `WebSymbolsQueryConfigurator.getScope()`'s `element` parameter can be: - a `JSObjectLiteralExpression` - Web Symbols should represent expected properties - a `JSExpression` - Web Symbols should represent available properties of the result of the expression. Parent expression is `JSReferenceExpression` or `JSIndexedPropertyAccessExpression` @@ -218,7 +217,7 @@ _2023.2+_ Web Symbols representing JavaScript symbols available for resolve of an unqualified JavaScript reference expression. Only dynamically contributed symbols (through [`WebSymbolsQueryConfigurator`](%gh-ic%/platform/webSymbols/src/com/intellij/webSymbols/query/WebSymbolsQueryConfigurator.kt)) have built-in support. -The `WebSymbolsQueryConfigurator.getScope`'s `element` parameter can be: +The `WebSymbolsQueryConfigurator.getScope()`'s `element` parameter can be: - an unqualified `JSReferenceExpression` - Web Symbols should represent possible symbols to which JavaScript reference could resolve. The reference actual name should not be taken into account when building the scope. Dedicated support for `WebSymbol` interface properties: @@ -238,14 +237,15 @@ The statically contributed symbols are available globally, depending on the cont The additional scope for matching DOM events is built from Web Symbols matching enclosing HTML element name. -For dynamic contributions the `WebSymbolsQueryConfigurator.getScope`'s `element` parameter can be: +For dynamic contributions the `WebSymbolsQueryConfigurator.getScope()`'s `element` parameter can be: - [`HtmlTag`](%gh-ic%/xml/xml-psi-api/src/com/intellij/psi/html/HtmlTag.java) - Web Symbols should represent available DOM events for matching. ## Using patterns for domain specific mappings -When a language feature (e.g. an HTML element) can represent some entity from a framework (e.g. a Vue component), you might want to -use a custom symbol kind with domain specific name (e.g. `vue-components`) and map from it to the language feature through a pattern. E.g. +When a language feature, such as an HTML element, is capable of representing an entity from a framework, +like a Vue component, it may be beneficial to employ a custom symbol kind with a domain-specific name (for example, `vue-components`), +and establish a mapping from this to the language feature via a pattern: ```json { diff --git a/topics/reference_guide/custom_language_support/websymbols_web_types.md b/topics/reference_guide/custom_language_support/websymbols_web_types.md index ec47795a3..e60c32047 100644 --- a/topics/reference_guide/custom_language_support/websymbols_web_types.md +++ b/topics/reference_guide/custom_language_support/websymbols_web_types.md @@ -11,8 +11,8 @@ The JSON Web Types detailed schema can be accessed by [following this link](https://github.com/JetBrains/web-types/blob/master/schema/web-types.json). The format is open source and IDE-agnostic by itself, however currently it is being actively used mostly by JetBrains IDEs. -It was originally created to facilitate the contribution of statically defined symbols for the -[Vue](https://vuejs.org/) framework, and therefore you might notice some deprecated properties in the schema. +Originally, it was created to facilitate the contribution of statically defined symbols for the +[Vue](https://vuejs.org/) framework, which may explain the presence of some deprecated properties in the schema. A simple Web Types file looks as follows, where this file defines a `my-element` HTML element with a `foo` attribute: