clean up documentation strings

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)

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

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

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

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

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

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