From 68b149b1b6fe2edf1d27d7f6404fc8c4f00cbdbd Mon Sep 17 00:00:00 2001 From: XeroOl Date: Fri, 9 Feb 2024 12:31:07 -0600 Subject: [PATCH] Update docs --- src/fennel-ls/compiler.fnl | 12 +++++++----- src/fennel-ls/diagnostics.fnl | 4 ++-- src/fennel-ls/dispatch.fnl | 1 - src/fennel-ls/formatter.fnl | 2 +- src/fennel-ls/json-rpc.fnl | 5 +---- src/fennel-ls/language.fnl | 20 ++++++++++++++++++-- src/fennel-ls/message.fnl | 5 ++--- src/fennel-ls/searcher.fnl | 3 ++- src/fennel-ls/state.fnl | 3 ++- 9 files changed, 35 insertions(+), 20 deletions(-) diff --git a/src/fennel-ls/compiler.fnl b/src/fennel-ls/compiler.fnl index 6cf3888..7cf633a 100644 --- a/src/fennel-ls/compiler.fnl +++ b/src/fennel-ls/compiler.fnl @@ -1,7 +1,9 @@ "Compiler -This file is responsible for the low level tasks of analysis. Its main job -is to recieve a file object and run all of the basic analysis that will be used -later by fennel-ls.language to answer requests from the client." +This module is responsible for calling the actual fennel parser and compiler, +and turning it into a \"fennel-ls file object\". It creates a plugin to the +fennel compiler, and then tries to store into it gets from the fennel compiler's +plugin hooks (aka callbacks). It stores lexical info about which identifiers +are declared / referenced in which places." (local {: sym? : list? : sequence? : table? : sym : view &as fennel} (require :fennel)) (local message (require :fennel-ls.message)) @@ -52,7 +54,7 @@ later by fennel-ls.language to answer requests from the client." (λ line+byte->range [self file line byte] (let [line (- line 1) - ;; TODO think about this further when upstream bug #180 is fixed + ;; TODO think about this further when upstream bug fennel#180 is fixed byte (math.max 0 byte) position (utils.pos->position file.text line byte self.position-encoding)] {:start position :end position})) @@ -108,7 +110,7 @@ later by fennel-ls.language to answer requests from the client." (action binding ?definition keys keys.multival) (list? binding) (let [nested? (not= depth 0)] - (if nested? (error (.. "I didn't expect to find a multival destructure in " (view binding) " at " (view keys)))) + (if nested? (error (.. "I didn't expect to find a nested multival destructure in " (view binding) " at " (view keys)))) (each [i child (ipairs binding)] (set keys.multival i) (recurse child keys (+ depth 1)) diff --git a/src/fennel-ls/diagnostics.fnl b/src/fennel-ls/diagnostics.fnl index 3b8411c..d3e7d64 100644 --- a/src/fennel-ls/diagnostics.fnl +++ b/src/fennel-ls/diagnostics.fnl @@ -1,6 +1,6 @@ "Diagnostics - -Goes through a file and mutates the `file.diagnostics` field, filling it with diagnostics." +Provides the function (check self file), which goes through a file and mutates +the `file.diagnostics` field, filling it with diagnostics." (local fennel (require :fennel)) (local language (require :fennel-ls.language)) diff --git a/src/fennel-ls/dispatch.fnl b/src/fennel-ls/dispatch.fnl index 49d43c1..5295443 100644 --- a/src/fennel-ls/dispatch.fnl +++ b/src/fennel-ls/dispatch.fnl @@ -3,7 +3,6 @@ This module is responsible for deciding which code to call in response to a given LSP request from the client. In general, this involves: -* parsing the message * determining the type of the message * calling the appropriate handler" diff --git a/src/fennel-ls/formatter.fnl b/src/fennel-ls/formatter.fnl index 2386507..9302332 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." +user code. Fennel-ls doesn't support user-code formatting as of now." (local {: sym? : view} (require :fennel)) diff --git a/src/fennel-ls/json-rpc.fnl b/src/fennel-ls/json-rpc.fnl index 63ef5a8..3260e22 100644 --- a/src/fennel-ls/json-rpc.fnl +++ b/src/fennel-ls/json-rpc.fnl @@ -5,12 +5,9 @@ There are only two functions exposed here: * `read` receives and parses a message from the client. * `write` serializes and sends a message to the client. -It's probably not compliant yet, because serialization of [] and {} is the same, -and there are also some places where a field has to be present, but filled with null. - +It's probably not compliant yet, because serialization of [] and {} is the same. Luckily, I'm testing with Neovim, so I can pretend these problems don't exist for now." -;; TODO find json library that doesn't conflate missing fields with null (local {: encode : decode} (require :json.json)) (λ read-header [in ?header] diff --git a/src/fennel-ls/language.fnl b/src/fennel-ls/language.fnl index 2c2e486..1610c00 100644 --- a/src/fennel-ls/language.fnl +++ b/src/fennel-ls/language.fnl @@ -1,6 +1,22 @@ "Language -The high level analysis system that does deep searches following -the data provided by compiler.fnl." +This module is for searching through the data provided by compiler.fnl. It +provides functions to search through a file. + +To find the defintion of something, we recursively search backward until we find +where something is defined. Yes it does a full search each time. +Imagine you have the following code. +```fnl +(local x 10) +(local y x) +(local z y) +z +``` +It doesn't forward propagate the \"type\" of x and y and z on compile. Instead, +any time information about x or y or z is needed, it recursively traverses the +definitions backward. + +As of now, there's no caching, but that could be a way to improve performance. +" (local {: sym? : list? : sequence? : varg? : sym : view} (require :fennel)) (local utils (require :fennel-ls.utils)) diff --git a/src/fennel-ls/message.fnl b/src/fennel-ls/message.fnl index 237ded9..f908ebc 100644 --- a/src/fennel-ls/message.fnl +++ b/src/fennel-ls/message.fnl @@ -2,9 +2,8 @@ Here are all the message constructor helpers for the various LSP and JSON-RPC responses that may need to be sent to the client. -I have them all here because I have a feeling I am conflating -missing fields with null fields, and I want to have one location -to look to fix this in the future." +This module is responsible for any tables that need to correlate 1:1 with the +LSP json objects." (local fennel (require :fennel)) (local utils (require :fennel-ls.utils)) diff --git a/src/fennel-ls/searcher.fnl b/src/fennel-ls/searcher.fnl index 62afc17..0ea4892 100644 --- a/src/fennel-ls/searcher.fnl +++ b/src/fennel-ls/searcher.fnl @@ -1,5 +1,6 @@ "Searcher -This file has all the logic needed to take the name of a module and find the corresponding URI. +This module is responsible for resolving (require) calls. It has all the logic +for using the name of a module and find the corresponding URI. I suspect this file may be gone after a bit of refactoring." (local fennel (require :fennel)) diff --git a/src/fennel-ls/state.fnl b/src/fennel-ls/state.fnl index 1ba9b4d..cedbdee 100644 --- a/src/fennel-ls/state.fnl +++ b/src/fennel-ls/state.fnl @@ -3,7 +3,8 @@ This module keeps track of the state of the language server. There are helpers to get files (get-by functions are all for getting files), and there's stuff for configuration options. There is no global state in this project: all state is stored -in the \"self\" object." +in the \"self\" object. Pretty much every \"self\" in the +entire fennel-ls project is referring to the same object." (local searcher (require :fennel-ls.searcher)) (local utils (require :fennel-ls.utils))