From 2859fb7f6539b569b48c3ddedda186f860ee9928 Mon Sep 17 00:00:00 2001 From: coder3101 Date: Mon, 20 Jul 2026 16:46:41 +0530 Subject: [PATCH] docs: Move usage to its own document Signed-off-by: coder3101 --- README.md | 51 ++------------------------------------------------- docs/usage.md | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 49 deletions(-) create mode 100644 docs/usage.md diff --git a/README.md b/README.md index 7dd22c3..26dd85e 100644 --- a/README.md +++ b/README.md @@ -33,16 +33,7 @@ - [Basic Configuration](#basic-configuration) - [Path Configuration](#path-configuration) - [Rename Configuration](#rename-configuration) -- [Usage](#-usage) - - [Code Completion](#code-completion) - - [Diagnostics](#diagnostics) - - [Code Formatting](#code-formatting) - - [Workspace Symbols](#workspace-symbols) - - [Document Symbols](#document-symbols) - - [Go to Definition](#go-to-definition) - - [Hover Information](#hover-information) - - [Rename Symbols](#rename-symbols) - - [Find References](#find-references) +- [Usage](docs/usage.md) - [Protocol Buffers Well-Known Types](#protocol-buffers-well-known-types) - [Packaging](#-packaging) - [Contributing](#-contributing) @@ -215,45 +206,7 @@ The `[config.rename]` section tunes rename behaviour. ## 🛠 Usage -Protols offers a rich set of features to enhance your `.proto` file editing experience. - -### Code Completion - -**Protols** offers intelligent autocompletion for messages, enums, and proto3 keywords within the current package. Simply start typing, and Protols will suggest valid completions. - -### Diagnostics - -Syntax errors are caught by the tree-sitter parser, which highlights issues directly in your editor. More advanced error reporting, is done by `protoc` which runs after a file saved. You must have `protoc` installed and added to your path or you can specify its path in the configuration above - -### Code Formatting - -Format your `.proto` files using `clang-format`. To customize the formatting style, add a `.clang-format` file to the root of your project. Both document and range formatting are supported. - -### Workspace Symbols - -Protols implements workspace symbol capabilities allowing you to search for symbols across workspace or list them, including nested symbols such as messages and enums. This allows for easy navigation and reference across workspace. - -### Document Symbols - -Protols provides a list of symbols in the current document, including nested symbols such as messages and enums. This allows for easy navigation and reference. - -### Go to Definition - -Jump directly to the definition of any custom symbol or imports, including those in other files or packages. This feature works across package boundaries. - -### Hover Information - -Hover over any symbol or imports to get detailed documentation and comments associated with it. This works seamlessly across different packages and namespaces. - -### Rename Symbols - -Rename symbols like messages, enums, services and RPC methods, and propagate the changes throughout the codebase. Rename also works when invoked on a type reference (e.g. the request or response type of an `rpc`) — the LSP pivots to the declaration and applies the rename from there. Field names, oneof names, and enum values can also be renamed at their declaration site (single-site rename, since they aren't referenced as types from other `.proto` files). - -When an `rpc` follows the `rpc (Request) returns (Response)` convention from the [Google API design guide](https://google.aip.dev/) (AIPs 131–136), renaming any one of the three triggers a chained rename of the other two — but only when (a) the matching message name follows the convention exactly, (b) the request/response is used by exactly one rpc in the workspace, and (c) the user's new name preserves the convention. If any check fails, only the symbol the user invoked rename on is renamed. - -### Find References - -Find all references to user-defined types like messages or enums. Nested fields are fully supported, making it easier to track symbol usage across your project. +For detailed usage instructions, see the [Usage Guide](docs/usage.md). ## Protocol Buffers Well-Known Types diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..55de30f --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,41 @@ +# Usage + +Protols offers a rich set of features to enhance your `.proto` file editing experience. + +## Code Completion + +**Protols** offers intelligent autocompletion for messages, enums, and proto3 keywords within the current package. Simply start typing, and Protols will suggest valid completions. + +## Diagnostics + +Syntax errors are caught by the tree-sitter parser, which highlights issues directly in your editor. More advanced error reporting, is done by `protoc` which runs after a file saved. You must have `protoc` installed and added to your path or you can specify its path in the configuration above + +## Code Formatting + +Format your `.proto` files using `clang-format`. To customize the formatting style, add a `.clang-format` file to the root of your project. Both document and range formatting are supported. + +## Workspace Symbols + +Protols implements workspace symbol capabilities allowing you to search for symbols across workspace or list them, including nested symbols such as messages and enums. This allows for easy navigation and reference across workspace. + +## Document Symbols + +Protols provides a list of symbols in the current document, including nested symbols such as messages and enums. This allows for easy navigation and reference. + +## Go to Definition + +Jump directly to the definition of any custom symbol or imports, including those in other files or packages. This feature works across package boundaries. + +## Hover Information + +Hover over any symbol or imports to get detailed documentation and comments associated with it. This works seamlessly across different packages and namespaces. + +## Rename Symbols + +Rename symbols like messages, enums, services and RPC methods, and propagate the changes throughout the codebase. Rename also works when invoked on a type reference (e.g. the request or response type of an `rpc`) — the LSP pivots to the declaration and applies the rename from there. Field names, oneof names, and enum values can also be renamed at their declaration site (single-site rename, since they aren't referenced as types from other `.proto` files). + +When an `rpc` follows the `rpc (Request) returns (Response)` convention from the [Google API design guide](https://google.aip.dev/) (AIPs 131–136), renaming any one of the three triggers a chained rename of the other two — but only when (a) the matching message name follows the convention exactly, (b) the request/response is used by exactly one rpc in the workspace, and (c) the user's new name preserves the convention. If any check fails, only the symbol the user invoked rename on is renamed. + +## Find References + +Find all references to user-defined types like messages or enums. Nested fields are fully supported, making it easier to track symbol usage across your project.