JeremyYao commented on code in PR #1495: URL: https://github.com/apache/daffodil-vscode/pull/1495#discussion_r2670464484
########## src/language/intellisense-development.md: ########## @@ -0,0 +1,169 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + +# Intellisense + +This document contains an overview of how intellisense works as well as a general view of the architecture of the code. + +## Table of Contents + +- [Intellisense](#intellisense) + - [Table of Contents](#table-of-contents) + - [General Intellisense Concepts](#general-intellisense-concepts) + - [Providers](#providers) + - [Registration](#registration) + - [DFDL](#dfdl) + - [High-level dfdl Intellisense Overview](#high-level-dfdl-intellisense-overview) + - [Provider Registration (Start Here)](#provider-registration-start-here) + - [Provider Implementation Locations](#provider-implementation-locations) + - [Helpers + Vocabulary](#helpers-vocabulary) + - [Context Parsing](#context-parsing) + - [Namespace / Prefix Handling](#namespace-prefix-handling) + - [Completions Construction](#completions-construction) + - [Hover / Documentation](#hover-documentation) + - [Testing](#testing) + - [Individual File Deep-Dives](#individual-file-deep-dives) + - [src/language/dfdl.ts](#srclanguagedfdlts) + - [TDML](#tdml) + +### General Intellisense Concepts + +#### Providers + +Providers in the VS Code API are extension points that let you plug specific language or editor features into the editor’s pipeline (e.g., completions, hovers, formatting). Proviers are implemented and then registered in the code which gets then gets called depending on the situation the provider activates. + +Many providers exist. Relevant ones that are used extensively in the code pertaining to IntelliSense functionality include `completionItemProvider` which provide code suggestions and `hoverProvider` which provider hover information. More information can be found at <https://code.visualstudio.com/api/references/vscode-api>. + +#### Registration + +After a provider has its functionality implemented, it can then be registered into the extension so that its functionality can be utilized in the IntelliSense functionality pipeline. Relevant registration calls include `registerCompletionItemProvider` and `registerHoverProvider`. + +### DFDL + +This section focuses on the `dfdl` Intellisense implementation. + +#### High-level dfdl Intellisense Overview + +This section providers a high-level view of the architecture of all relevant code items pertaining to the `dfdl` IntelliSense functionality. + +##### Provider Registration (Start Here) + +`src/language/dfdl.ts` is the starting point. It wires up the extension’s language features by calling VS Code registration APIs (e.g., `registerCompletionItemProvider`, `registerHoverProvider`, and similar) that are then customized as functions that provide customized provider functinoality. + +In other words, `dfdl.ts` connects the provider implementations to VS Code for the DFDL language. + +##### Provider Implementation Locations + +Autocompletion logic is split into multiple provider modules under `src/language/providers/`, each handling different completion scenarios. + +- `elementCompletion.ts` -- suggests child elements / element tags. +- `attributeCompletion.ts` -- suggests attribute names when inside an element. +- `attributeValueCompletion.ts` -- provides completion suggestions for attribute values (e.g., enumerated values). +- `closeElement.ts`, `closeElementSlash.ts` -- completions for closing tags and slash completions. +- `attributeHover.ts` -- hover provider that shows attribute documentation/available attributes. + +It should be noted that there are many `registerCompletionItemProvider` calls. The implemented `completionItemProvider`s each contain logic to determine whether or not it the provider is relevant to a given situation or not. + +##### Helpers + Vocabulary + +`src/language/providers/utils.ts` and `src/language/providers/intellisense/commonItems.ts` contain shared helpers for constructing CompletionItem objects, and context parsing utilities used by many providers. For `src/language/providers/intellisense/commonItems.ts` and tracing through usage, it's used by `attributeCompletion.ts` and `elementCompletion.ts`. Review Comment: Omitted mentions of CommonItems and condensed it to ``src/language/providers/utils.ts` contain shared helpers for constructing CompletionItem objects, and context parsing utilities used by many providers. It also contains utilities used for root-level completion logic (common completion primitives).` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
