Update docs

src/fennel-ls/compiler.fnl

@@ -1,7 +1,9 @@
 "Compiler
-This file is responsible for the low level tasks of analysis. Its main job
+This module is responsible for calling the actual fennel parser and compiler,
-is to recieve a file object and run all of the basic analysis that will be used
+and turning it into a \"fennel-ls file object\". It creates a plugin to the
-later by fennel-ls.language to answer requests from the client."
+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))

src/fennel-ls/diagnostics.fnl

@@ -1,6 +1,6 @@
 "Diagnostics
-
+Provides the function (check self file), which goes through a file and mutates
-Goes through a file and mutates the `file.diagnostics` field, filling it with diagnostics."
+the `file.diagnostics` field, filling it with diagnostics."
 
 (local fennel (require :fennel))
 (local language (require :fennel-ls.language))

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"
 

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))

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,
+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.
-
 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]

src/fennel-ls/language.fnl

@@ -1,6 +1,22 @@
 "Language
-The high level analysis system that does deep searches following
+This module is for searching through the data provided by compiler.fnl. It
-the data provided by compiler.fnl."
+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))

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
+This module is responsible for any tables that need to correlate 1:1 with the
-missing fields with null fields, and I want to have one location
+LSP json objects."
-to look to fix this in the future."
 
 (local fennel (require :fennel))
 (local utils (require :fennel-ls.utils))

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))

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))