From c5f36ac81337b648ade2cfbcd8990c6e2727f66a Mon Sep 17 00:00:00 2001 From: XeroOl Date: Mon, 14 Jul 2025 01:14:31 -0500 Subject: [PATCH] clean up documentation strings --- docs/linting.md | 2 +- src/fennel-ls/completion.fnl | 36 +++++++++++++++++++++++++++++++++++- src/fennel-ls/config.fnl | 8 ++++---- src/fennel-ls/dispatch.fnl | 3 +-- src/fennel-ls/docs.fnl | 7 +++++++ src/fennel-ls/files.fnl | 9 ++------- src/fennel-ls/formatter.fnl | 6 +++--- 7 files changed, 53 insertions(+), 18 deletions(-) diff --git a/docs/linting.md b/docs/linting.md index 80da4ce..104d8d6 100644 --- a/docs/linting.md +++ b/docs/linting.md @@ -6,7 +6,7 @@ Go into `src/fennel-ls/lint.fnl` and create a new call to add-lint. ## Writing your lint Now, the fun part: writing your lint function. -The goal is to check whether the given arguments should emit a warning, and +A lint checks whether the given arguments should emit a warning, and what message to show. You can request that your lint is called for every * function-call (Every time the user calls a function) * special-call (Every time the user calls a special) diff --git a/src/fennel-ls/completion.fnl b/src/fennel-ls/completion.fnl index b065185..3dfa62e 100644 --- a/src/fennel-ls/completion.fnl +++ b/src/fennel-ls/completion.fnl @@ -1,3 +1,33 @@ +"Completion + +LSP Spec: +> * to achieve consistency across languages and to honor different clients +> usually the client is responsible for filtering and sorting. This has also +> the advantage that client can experiment with different filter and sorting +> models. + +Because of this, fennel-ls' job in completions is to report every single +possible completion, without being clever about filtering. To do this, we +iterate over the current scope, and recursively explore every field of every +variable. + +This creates large completion messages, so we have an optimization trick: + +LSP says that clients need to support resolving documentation/detail for +completion items lazily. This lazy resolution is very important because we +can skip sending the documentation for every possible completion until client +until it asks for each one. The documentation ends up being significantly more +than half of the completion response. + +Although clients always support this lazy resolution, fennel-ls can only provide +it if it receives enough information in the completionItem/resolve request to +actually recover the original completion. If the client supports both +CompletionClientCapabilites.completionList.itemDefaults.editRange and +CompletionClientCapabilites.completionList.itemDefaults.data, then we can ask +the client to forward information to the resolve request by setting the `data` +to {: uri : byte}. When this capability exists, `server.can-do-good-completions?` +is set to true and we report that we support completionItem/resolve." + (local files (require :fennel-ls.files)) (local utils (require :fennel-ls.utils)) (local analyzer (require :fennel-ls.analyzer)) @@ -14,7 +44,11 @@ :true {:metadata {:fnl/docstring "A boolean value representing truth." :fls/itemKind "Keyword"}} :false {:metadata {:fnl/docstring "A boolean value representing falsehood." - :fls/itemKind "Keyword"}}}) + :fls/itemKind "Keyword"}} + :.nan {:metadata {:fnl/docstring "NaN" + :fls/itemKind "Constant"}} + :.inf {:metadata {:fnl/docstring "inf" + :fls/itemKind "Constant"}}}) (λ textDocument/completion [server _send {: position :textDocument {: uri}}] ;; get the file diff --git a/src/fennel-ls/config.fnl b/src/fennel-ls/config.fnl index c36062a..820c58b 100644 --- a/src/fennel-ls/config.fnl +++ b/src/fennel-ls/config.fnl @@ -1,9 +1,9 @@ -"Settings +"Config This module is in charge of setting up the default settings. -Settings can be read without requiring this module: just look in `server.configuration`. -There are no global settings. They're all stored in the `server` object. -" +Settings are stored in `server.configuration`. +config.reload should be the only function that ever writes +to server.configuration. Every other use case should be read-only." ;; TODO: Settings to set the warning levels of lints ;; Setting to allow all globals diff --git a/src/fennel-ls/dispatch.fnl b/src/fennel-ls/dispatch.fnl index 2e3c4b6..d4beaf6 100644 --- a/src/fennel-ls/dispatch.fnl +++ b/src/fennel-ls/dispatch.fnl @@ -4,8 +4,7 @@ to a given LSP request from the client. In general, this involves: * determining the type of the message -* calling the appropriate handler in the :fennel-ls.handlers module. -" +* calling the appropriate handler in the :fennel-ls.handlers module." (local handlers (require :fennel-ls.handlers)) (local message (require :fennel-ls.message)) diff --git a/src/fennel-ls/docs.fnl b/src/fennel-ls/docs.fnl index bc9a728..32ba7ce 100644 --- a/src/fennel-ls/docs.fnl +++ b/src/fennel-ls/docs.fnl @@ -1,3 +1,10 @@ +"Docs + +Handles grabbing the documentation from sources other than fennel code; +* Lua Standard Library (generated from the lua manuals) +* Fennel's special forms and macros (taken from internal `fennel.compiler` API) +* external user docsets (from the user's filesystem)" + (local {: path-join} (require :fennel-ls.utils)) (local fennel (require :fennel)) (local {:metadata METADATA diff --git a/src/fennel-ls/files.fnl b/src/fennel-ls/files.fnl index 1cca814..d78b15a 100644 --- a/src/fennel-ls/files.fnl +++ b/src/fennel-ls/files.fnl @@ -1,10 +1,5 @@ -"State -This module keeps track of the state of the language server: -* Settings -* Loaded files - -There is no global state in this project: all state is stored -in the \"server\" object." +"Files +This module has high level helpers for creating/getting \"file\" objects." (local searcher (require :fennel-ls.searcher)) (local utils (require :fennel-ls.utils)) diff --git a/src/fennel-ls/formatter.fnl b/src/fennel-ls/formatter.fnl index 58a439e..76a1fdb 100644 --- a/src/fennel-ls/formatter.fnl +++ b/src/fennel-ls/formatter.fnl @@ -1,7 +1,7 @@ "Formatter -This module is for formatting code that needs to be shown to the client -in tooltips and other notification messages. It is NOT for formatting -user code. Fennel-ls doesn't support user-code formatting as of now." +This module is for converting various objects to markdown that needs to be +shown to the client in tooltips and other notification messages. It is NOT for +formatting user code. Fennel-ls doesn't support user-code formatting as of now." (local {: sym? : view