Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add descriptions for handlers in codebase walkthrough #5725

Merged
merged 2 commits into from
Jan 25, 2022
Merged

Add descriptions for handlers in codebase walkthrough #5725

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7843338
Add descriptions for handlers
shenglol Jan 25, 2022
91873d2
Add a link
shenglol Jan 25, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions docs/codebase.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,24 +59,24 @@ This lives in the [bicep-types-az](https://github.com/Azure/bicep-types-az) repo
The Bicep language server contains the following handlers located in the [Handlers](../src/Bicep.LangServer/Handlers) folder:
| Name | Description |
| :--- | :---------- |
| [`BicepBuildCommandHandler`](../src/Bicep.LangServer/Handlers/BicepBuildCommandHandler.cs) | TODO |
| [`BicepCodeActionHandler`](../src/Bicep.LangServer/Handlers/BicepCodeActionHandler.cs) | TODO |
| [`BicepCompletionHandler`](../src/Bicep.LangServer/Handlers/BicepCompletionHandler.cs) | TODO |
| [`BicepDefinitionHandler`](../src/Bicep.LangServer/Handlers/BicepDefinitionHandler.cs) | TODO |
| [`BicepDeploymentGraphHandler`](../src/Bicep.LangServer/Handlers/BicepDeploymentGraphHandler.cs) | TODO |
| [`BicepDidChangeWatchedFilesHandler`](../src/Bicep.LangServer/Handlers/BicepDidChangeWatchedFilesHandler.cs) | TODO |
| [`BicepDocumentFormattingHandler`](../src/Bicep.LangServer/Handlers/BicepDocumentFormattingHandler.cs) | TODO |
| [`BicepDocumentHighlightHandler`](../src/Bicep.LangServer/Handlers/BicepDocumentHighlightHandler.cs) | TODO |
| [`BicepDocumentSymbolHandler`](../src/Bicep.LangServer/Handlers/BicepDocumentSymbolHandler.cs) | TODO |
| [`BicepHoverHandler`](../src/Bicep.LangServer/Handlers/BicepHoverHandler.cs) | TODO |
| [`BicepReferencesHandler`](../src/Bicep.LangServer/Handlers/BicepReferencesHandler.cs) | TODO |
| [`BicepRegistryCacheRequestHandler`](../src/Bicep.LangServer/Handlers/BicepRegistryCacheRequestHandler.cs) | TODO |
| [`BicepRenameHandler`](../src/Bicep.LangServer/Handlers/BicepRenameHandler.cs) | TODO |
| [`BicepSemanticTokensHandler`](../src/Bicep.LangServer/Handlers/BicepSemanticTokensHandler.cs) | TODO |
| [`BicepSignatureHelpHandler`](../src/Bicep.LangServer/Handlers/BicepSignatureHelpHandler.cs) | TODO |
| [`BicepTelemetryHandler`](../src/Bicep.LangServer/Handlers/BicepTelemetryHandler.cs) | TODO |
| [`BicepTextDocumentSyncHandler`](../src/Bicep.LangServer/Handlers/BicepTextDocumentSyncHandler.cs) | TODO |
| [`InsertResourceHandler`](../src/Bicep.LangServer/Handlers/InsertResourceHandler.cs) | TODO |
| [`BicepBuildCommandHandler`](../src/Bicep.LangServer/Handlers/BicepBuildCommandHandler.cs) | Handles the `build` custom LSP request sent from the language client when the user execute the "Build" custom command for a Bicep file in VS Code. When processing the request, the handler invokes the Bicep compiler to compile the Bicep file and emit an ARM template for the Bicep file. |
| [`BicepCodeActionHandler`](../src/Bicep.LangServer/Handlers/BicepCodeActionHandler.cs) | Handles the [Code Action](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction) request. In VS Code, an available Code Action is indicated by a lightbulb near the source code when the cursor is hovered on a squiggle or selected text region. The current available code actions for the Bicep language include code fixes to either fix misspelled symbols and property names or to disable linter rules inline. The former is done by calling the [`SpellChecker.GetSpellingSuggestion`](../src/Bicep.Core/Text/SpellChecker.cs) utility method to check symbol and property names in the semantic analysis and type checking steps when compiling a Bicep file. For implementation details about how linter rules are disabled, see the source code of the handler. |
| [`BicepCompletionHandler`](../src/Bicep.LangServer/Handlers/BicepCompletionHandler.cs) | Handles the [Completion](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion) request. The request is sent by the language client to compute completion items at a given cursor position when the user press `Ctrl+Space` or type a trigger character (such as the dot character after a symbol reference). The key of computing completion items is to find the corresponding syntax tree node at the cursor position and use the combination of the the syntax tree node and the cursor position to determine what completion items can be provided. The logic is encapsulated in the [BicepCompletionProvider](../src/Bicep.LangServer/Completions/BicepCompletionProvider.cs) class. |
| [`BicepDefinitionHandler`](../src/Bicep.LangServer/Handlers/BicepDefinitionHandler.cs) | Handles the [Goto Definition](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_definition) request sent by the language client to resolve the definition location of a symbol at a given Bicep file position. This is done by compiling the Bicep file to build a symbol table and calling the `ResolveSymbol` method defined on the [`BicepSymbolResolver`](../src/Bicep.LangServer/Providers/BicepSymbolProvider) class. |
| [`BicepDeploymentGraphHandler`](../src/Bicep.LangServer/Handlers/BicepDeploymentGraphHandler.cs) | Handles the `textDocument/deploymentGraph` custom LSP request sent by the Bicep VSCode extension when the user runs the "Open Visualizer" or "Open Visualizer to Side" command. The handler builds a resource deployment dependency graph by using the resource dependency information provided by [`ResourceDependencyVisitor`](../src/Bicep.Core/Emit/ResourceDependencyVisitor.cs) (which is also used to generate `dependsOn` when emitting ARM templates). Once the graph is returned to the Bicep VSCode extension, a webview will be opened to render the graph. |
| [`BicepDidChangeWatchedFilesHandler`](../src/Bicep.LangServer/Handlers/BicepDidChangeWatchedFilesHandler.cs) | Handles the [`DidChangeWatchedFiles`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_didChangeWatchedFiles) notification sent from the language client when the client detects changes to files and folders watched by the handler. The watched files include Bicep files, Bicep configuration files, and ARM template files. When invoked, the handler refreshes compilation of all source files in the workspace to make sure the language server is in sync with the language client. |
| [`BicepDocumentFormattingHandler`](../src/Bicep.LangServer/Handlers/BicepDocumentFormattingHandler.cs) | Handles the [Document Formatting](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting) request. Upon execution, it calls the `PrintProgram` method defined on the [`PrettyPrinter`] class which invokes [`DocumentBuildVisitor`](../src/Bicep.Core/PrettyPrint/DocumentBuildVisitor) to walk the syntax tree of the given Bicep file and outputs a formatted string for that syntax tree based on a set of formatting rules defined for each syntax tree node type. |
| [`BicepDocumentHighlightHandler`](../src/Bicep.LangServer/Handlers/BicepDocumentHighlightHandler.cs) | Handles the [Document Highlight](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting) request. This highlights all references to the symbol where the cursor is placed in a Bicep file. The handler first calls the `ResolveSymbol` method of an [`BicepSymbolResolver`](../src/Bicep.LangServer/Providers/BicepSymbolResolver.cs) instance to find the symbol at the give file position. The references are then found by calling the `FindReferences` method defined on the [`SemanticModel`](../src/Bicep.Core/Semantics/SemanticModel.cs) class. They are further converted to a collection of [DocumentHighlight](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#documentHighlight) and returned to the client. |
| [`BicepDocumentSymbolHandler`](../src/Bicep.LangServer/Handlers/BicepDocumentSymbolHandler.cs) | Handles the [Document Symbol](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_documentSymbol) request. The returned result is a list of [`DocumentSymbol`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#documentSymbol) scoped to a Bicep file. The handler queries the semantic model of the Bicep file to get all declarations and then converts the symbolic name of each declaration to a `DocumentSymbol`. |
| [`BicepHoverHandler`](../src/Bicep.LangServer/Handlers/BicepHoverHandler.cs) | Handles the [Hover](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textDocument_hover) request. It is sent from the language client to the server to request hover information of a symbol at a given Bicep file position. Typical hover information includes parameter descriptions, variable type information, etc. The handler uses [`BicepSymbolResolver`](../src/Bicep.LangServer/Providers/BicepSymbolProvider) to get the symbol at the requested position and generate the corresponding hover information based on the symbol type. |
| [`BicepReferencesHandler`](../src/Bicep.LangServer/Handlers/BicepReferencesHandler.cs) | Handles the [Find References](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textDocument_references) request. The references request is sent from the client to the server to resolve workspace-wide references for the symbol denoted by the given Bicep file position. Similar to `BicepDocumentHighlightHandler`, `BicepReferencesHandler` queries the semantic model to resolve all references of the symbol found at the given file position. |
| [`BicepRegistryCacheRequestHandler`](../src/Bicep.LangServer/Handlers/BicepRegistryCacheRequestHandler.cs) | Handles the `textDocument/bicepCache` custom LSP request. The request is sent by the client to resolve contents of document URIs using the bicep-cache:// scheme. The `BicepDefinitionHandler` returns such URIs when the user execute the "Goto Definition" command and the definition is inside a module that resides in the local module cache. |
| [`BicepRenameHandler`](../src/Bicep.LangServer/Handlers/BicepRenameHandler.cs) | Handles the [Rename](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textDocument_rename) request. The rename request is sent from the client to the server to ask the server to compute a workspace change so that the client can perform a workspace-wide rename of a symbol. This is done by querying the semantic model to find all references of a resolved symbol and returning a collection of [TextEdit](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textEdit) to be applied to the text ranges of the references on the client side. |
| [`BicepSemanticTokensHandler`](../src/Bicep.LangServer/Handlers/BicepSemanticTokensHandler.cs) | Handles the [Semantic Tokens](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textDocument_semanticTokens) request. The request is sent from the client to the server to resolve semantic tokens for a given Bicep file. Semantic tokens are used to provide more color information in addition to syntax highlighting based on the Bicep TextMate grammar ([bicep.tmlanguage](../src/vscode-bicep/syntaxes/bicep.tmlanguage)) defined in the Bicep VSCode extension. The handler builds semantic tokens for a give Bicep file by calling the `BuildSemanticTokens` method of the [`SemanticTokenVisitor`](../src/Bicep.LangServer/SemanticTokenVisitor.cs) class. |
| [`BicepSignatureHelpHandler`](../src/Bicep.LangServer/Handlers/BicepSignatureHelpHandler.cs) | Handles the [Signature Help](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textDocument_signatureHelp) request. The signature help request is sent from the client to the server to request signature information at a given cursor position. The handling process involves resolving the function symbol at the given cursor position and generating a [SignatureHelp](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#signatureHelp) using the function symbol's type information. |
| [`BicepTelemetryHandler`](../src/Bicep.LangServer/Handlers/BicepTelemetryHandler.cs) | Handles the [`workspace/executeCommand`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#workspace_executeCommand) LSP request when the command name is `bicep.Telemetry`. This handler is used to collect telemetry data. |
| [`BicepTextDocumentSyncHandler`](../src/Bicep.LangServer/Handlers/BicepTextDocumentSyncHandler.cs) | Handles the [`textDocument/didOpen`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textDocument_didOpen), [`textDocument/didChange`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textDocument_didChange), and [`textDocument/didClose`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textDocument_didClose) notifications. The notifications are sent when a Bicep file is opened, edited, or closed. The handler creates or refreshes compilation for the given Bicep file to keep the client and the server in sync. |
| [`InsertResourceHandler`](../src/Bicep.LangServer/Handlers/InsertResourceHandler.cs) | Hanldes the custom `textDocument/insertResource` LSP request. The request is sent by the language client to the server when the user runs the "Insert Resource" command in VSCode. The request contains a resource ID of the resource to be inserted in a Bicep file. The handler sends an HTTP request to Azure with the resource ID to get the payload of the resource in JSON format. The JSON payload is then "decompiled" to a Bicep resource declaration and returned to the client. |

## CLI Structure
The Bicep CLI exposes various commands, each of which implements the [ICommand](../src/Bicep.Cli/Commands/ICommand.cs) interface.
Expand Down