docs: update type and module descriptions

docs/config.norg

@@ -16,7 +16,7 @@ tangle: {
     delimiter: none
 }
 created: 2023-11-17T16:29:17+0100
-updated: 2023-11-17T16:32:27+0100
+updated: 2024-06-09T11:35:45+0100
 version: 1.1.1
 @end
 
@@ -32,7 +32,7 @@ version: 1.1.1
   rest of the configuration which is for configuring neocomplete itself.
 
 ** UI
-   In the ui field the completion-menu, the docs-view and the format of the entries are configured.
+   In the ui field the completion menu, the docs view and the format of the entries are configured.
    There is also a field for configuring type icons.
    #tangle
    @code lua
@@ -56,7 +56,8 @@ version: 1.1.1
    @end
 
 ** Keyword pattern
-   Pattern used to determine keywords, used to determine what to use for filtering and 
+   Pattern used to determine keywords, used to determine what to use for filtering and what to
+   remove if insert text is used.
    #tangle
    @code lua
    --- Pattern used to determine keywords
@@ -66,7 +67,6 @@ version: 1.1.1
 ** Enabled
    This function can be used to disable neocomplete in certain contexts. By default this disables
    neocomplete in prompts.
-
    #tangle
    @code lua
    --- Configuration for the ui of neocomplete
@@ -82,7 +82,8 @@ version: 1.1.1
   --- The main class for the ui configuration of neocomplete.nvim
   ---@class neocomplete.config.ui
   @end
-  The most important part for many users will be the `menu` field. It's used to configure the completion menu.
+  The most important part for many users will be the `menu` field. It's used to configure the
+  completion menu.
   #tangle
   @code lua
   --- Configuration of the completion menu of neocomplete.nvim
@@ -110,6 +111,7 @@ version: 1.1.1
    --- Configuration of the completion menu of neocomplete.nvim
    ---@class neocomplete.config.ui.menu
    @end
+
    It includes some basic window properties like the border and the maximum height of the window.
    #tangle
    @code lua
@@ -180,7 +182,6 @@ version: 1.1.1
 
 ** Type Icons
    This is a table which defines the different icons.
-
    #tangle
    @code lua
    --- The icons used for the different completion item types

docs/context.norg

@@ -9,7 +9,7 @@ categories: [
     types
 ]
 created: 2023-11-15T17:42:46+0100
-updated: 2024-06-07T21:22:41+0100
+updated: 2024-06-09T14:47:28+0100
 tangle: {
     languages: {
         lua: ../lua/neocomplete/types/context.lua
@@ -21,62 +21,69 @@ version: 1.1.1
 @end
 
 * Completion Context
+  This is a class representing the current state. It includes buffer number and cursor position. It
+  is passed to completion sources to get completions.
   #tangle
   @code lua
   --- Context provided to completion sources
   ---@class neocomplete.context
   @end
 
+* Methods
 ** Changed
-   Whether the context changed in comparison to the previous one
+   Whether the context changed in comparison to the previous one. This is used to check whether to
+   get new completions or not.
    #tangle
    @code lua
    --- Context changed since previous
    ---@field changed fun(neocomplete.context): boolean
    @end
 
 ** New
-   Create a new context
+   Create a new context. This takes the previous one as argument. This one is stored to determine if
+   the context changed or not when completing.
+   The previous context of the previous one is deleted so this data structure doesn't grow really
+   large.
    #tangle
    @code lua
    --- Create a new context
-   ---@field new fun(neocomplete.context?): neocomplete.context
+   ---@field new fun(previous: neocomplete.context?): neocomplete.context
    @end
 
+* Fields
 ** Previous
-   The previous context which is used to determine whether the context changed or not
+   The previous context which is used to determine whether the context changed or not.
    #tangle
    @code lua
    --- The previous context
    ---@field previous neocomplete.context?
    @end
 
 ** Cursor
+   The cursor positon.
    #tangle
    @code lua
    --- The cursor position
    ---@field cursor neocomplete.context.cursor
    @end
 
 ** Bufnr
-   Number of the buffer
+   Number of the buffer.
    #tangle
    @code lua
    --- The number of the buffer
    ---@field bufnr integer
    @end
 
 ** Reason
-   Reason for triggering completion
+   Reason for triggering completion.
    #tangle
    @code lua
    --- Reason for triggering completion
    ---@field reason neocomplete.completionReason?
    @end
 
-
-
-
+* Misc
    #tangle
    @code lua
    --- A cursor position

docs/core.norg

@@ -9,7 +9,7 @@ categories: [
     types
 ]
 created: 2023-11-15T17:42:46+0100
-updated: 2024-06-07T21:25:42+0100
+updated: 2024-06-09T10:21:16+0100
 tangle: {
     languages: {
         lua: ../lua/neocomplete/types/core.lua
@@ -21,43 +21,35 @@ version: 1.1.1
 @end
 
 * General
+  This module is for the core of neocomplete. There all comes together with the menu being opened
+  and the completion triggered.
   #tangle
   @code lua
-  --- The core of neocomplete where the main api functions are defined
+  --- The core module of neocomplete
   ---@class neocomplete.core
   @end
 
 ** New
-   Creates a new core instance
+   Use this function to create a new instance.
    #tangle
    @code lua
    --- Create a new instance of the core
    ---@field new fun(): neocomplete.core
    @end
 
-** Context
-   #tangle
-   @code lua
-   --- Context instance of the core
-   ---@field context neocomplete.context
-   @end
-
-** Menu
-   #tangle
-   @code lua
-   --- Menu instance of the core
-   ---@field menu neocomplete.menu
-   @end
-
+* Methods
 ** Complete
-   The main function which starts the completion
+   This function starts the completion. It goes through all the sources, triggers them (completion
+   or sorting) and opens the menu with the result.
    #tangle
    @code lua
    --- Complete
    ---@field complete fun(self: neocomplete.core, reason: neocomplete.completionReason?): nil
    @end
 
 ** On Change
+   This function is invoked on every text change. It updates the context field and triggers
+   completion if it changed.
    #tangle
    @code lua
    --- The function that gets invoked when the text changes
@@ -66,9 +58,27 @@ version: 1.1.1
 
 ** Setup
    The setup function is used to setup neocomplete so it will actually provide autocompletion when
-   typing.
+   typing by setting up an autocommand.
    #tangle
    @code lua
    --- Setup core (for now autocommands)
    ---@field setup fun(self: neocomplete.core): nil
    @end
+
+* Fields
+** Context
+   This is used to store the current context. There is always a new one created in `on_change` and
+   compared to see if it changed.
+   #tangle
+   @code lua
+   --- Context instance of the core
+   ---@field context neocomplete.context
+   @end
+
+** Menu
+   In this field a menu instance which is used in core is stored.
+   #tangle
+   @code lua
+   --- Menu instance of the core
+   ---@field menu neocomplete.menu
+   @end

docs/design.norg

@@ -1,8 +1,12 @@
 @document.meta
 title: Design
 description: Design of neocomplete.nvim
-authors: [max397574]
-categories: [docs]
+authors: [
+    max397574
+]
+categories: [
+    docs
+]
 created: 2023-11-15T17:42:49+0100
 updated: 2023-11-15T17:42:49+0100
 version: 1.1.1
@@ -30,34 +34,30 @@ version: 1.1.1
     -- Try to get nicely concealed like in core or noice.nvim
     -- Allow to send to e.g. quickfix or copy
 
-** Source
-
-** Types
-   - {:./types/source:}
-
 
 * Architecture
   TODO: fancy ascii diagramms
 
   autocompletion:
   ~ `TextChangedI` or `CursorMovedI`
-  ~ Check if character was a trigger character or you're in specific context e.g. at beginning of line or word
+  ~ get the context (line before, cursor position etc)
+  ~ Check if context changed
+  ~ Check if character was a trigger character or completion was triggered manually
   ~ Depending on ^^ decide what to do /for every source/:
   -- Get new completions
-  ~~~ get the context (line before, cursor position etc)
   ~~~ get completions from source based on context
   -- sort completions
-  ~~~ use character typed to fuzzy match and sort completions
-  ~ display things
-  ~~ figure out top matching completions
+  ~~~ Use characters found with `keyword_pattern` to fuzzy match and sort completions
+  ~ Collect all the completions
+  ~ Open menu to display thing
   ~~ if there is a selected one:
   --- highlight selected one
   --- show preview of selected completion
   --- show docs
 
-  When pressing e.g. `<cr>`:
+  When completing (e.g. `<cr>`):
   ~ check if menu is open
-  ~ check if anything is selected
+  ~ check if anything is selected (or autoselect option)
   ~ complete
   ~~ insert text
   ~~ additional text edits (check core functions)
@@ -81,11 +81,11 @@ version: 1.1.1
     (understandable to a certain degree) afraid of making breaking changes and fixing them or just
     doesn't think changes are necessary.
 
-**** Configuraton of item display
+**** Configuration of item display
      One such example is the configuration of how items are displayed in the menu. This works with
      a function `formatting` which takes a completion item and is allowed to return an item where
      the three fields `menu`, `kind` and `abbr` and three more fields for highlights for those can
-     be set. So appart from the background and border color of the menu you're limited to have three
+     be set. So apart from the background and border color of the menu you're limited to have three
      different fields and colors in your menu E.g. source name, kind name, kind icon and text isn't
      possible. It's also not possible to have round or half blocks around icons because you don't
      have enough colors. An example of an issue can be found {https://github.com/hrsh7th/nvim-cmp/issues/1599}[here].
@@ -109,7 +109,7 @@ version: 1.1.1
     according to the author. Even though there was clearly a problem described and what the pr would
     allow (this pr allowed custom fields which still isn't nice but fixed the obvious problems).
     There were also some features (in particular the custom scrollbars) removed because there were
-    some issues with it which apperently weren't worth fixing for the feature.
+    some issues with it which apparently weren't worth fixing for the feature.
     So it's not really motivating to try to contribute new things. It's also quite hard because of
     the messy code with lots of legacy code.
 
@@ -129,35 +129,43 @@ version: 1.1.1
    In the future we'd like to allow injecting custom views via config where you just get the
    entries and do things with them yourself. This is mostly to avoid code duplication in core.
 
-* Types
-  TODO: tangle those into files?
-  TODO: perhaps move to different file?
+** Commandline completion
+   At the moment no command line completion is planned. This is because the author thinks it's not
+   really needed because builtin completion is already quite good and there is little value added
+   by adding commandline completion. Also it doesn't really make sense in my opinion to combine
+   commandline completion and autocompletion for buffer contents in the same plugin. Especially if
+   you try to share things in between like nvim-cmp does.
+
+* Types used
   The types should minimally be the lsp things (for the context passed to source, for response and
-  for entries). Everything additionally just optional.
-  @code lua
-  ---A source for neocomplete
-  ---@class neocomplete.source
-  ---@field
-  @end
+  for entries). Everything additionally is mostly optional.
 
 * Code style
 ** Object-Orientation
-   TOOD: decide
-   avoid for utils?
-   menu, view, entry, source oop?
+   Most of the modules are written object oriented. This decision was made because it's way easier
+   to create new instances of the things and associate data with them.
+
 ** Functions
    You should always write functions in the form of `[local] function <name>(<parameters>)` as
    opposed to `[local <name> = function(<parameters>)`. The first notation provides the advantage
    that you can directly jump to it's definition and you won't get multiple results (the name and
    the anonymous function).
+
 ** Comments and annotations
-   Add annotations to every public function of a module (e.g. with neogen) and add comments
+   Add annotations to *every* public function of a module (e.g. with neogen) and add comments
    explaining what the code does. We'd like to have code which would be understandable for outsiders.
+   Also try to add annotations and descriptions to local functions but this isn't as important as
+   public ones
 
 *** Format
-    TODO: decide whether we want spaces after `---` or not
+    For The annotations we use {https://luals.github.io/wiki/annotations/}[LuaCATS] style. For types
+    don't use a space after the `---` marker. For comments you should. Check the code blocks in
+    `docs/` for examples.
 
 ** Types
    We have files for types which are tangled from a norg file (this one?) using lua-ls annotations.
-   They are prefixed with `neocomplete`.
-   As often as possible we should try to use the `lsp.*` types which are in neovim core (TODO: perhaps only on 0.10? but we don't care).
+   They are prefixed with `neocomplete.`.
+   As often as possible we should try to use the `lsp.*` types which are in neovim core.
+
+   The types are documented in the `docs/` folder and are tangled to lua type files with {https://github.com/nvim-neorg/neorg}[neorg].
+   So if you want to change a type annotation you should change the `.norg` file and tangle it again.