[Lua]: Add annotations to the core codebase.

lua/neorg.lua

@@ -1,35 +1,36 @@
---[[
---    ROOT NEORG FILE
---    This file is the beginning of the entire plugin. It's here that everything fires up and starts pumping.
---]]
+--- @brief [[
+--- This file marks the beginning of the entire plugin. It's here that everything fires up and starts pumping.
+--- @brief ]]
 
--- Require the most important modules
 local neorg = require("neorg.core")
 local config, log, modules = neorg.config, neorg.log, neorg.modules
 
---- This function takes in a user config, parses it, initializes everything and launches neorg if inside a .norg or .org file
----@param cfg table #A table that reflects the structure of config.user_config
+--- @module "neorg.core.config"
+
+--- Initializes Neorg. Parses the supplied user configuration, initializes all selected modules and adds filetype checking for `.norg`.
+--- @param cfg neorg.configuration.user A table that reflects the structure of `config.user_config`.
+--- @see config.user_config
+--- @see neorg.configuration.user
 function neorg.setup(cfg)
     config.user_config = vim.tbl_deep_extend("force", config.user_config, cfg or {})
 
-    -- Create a new global instance of the neorg logger
+    -- Create a new global instance of the neorg logger.
     log.new(config.user_config.logger or log.get_default_config(), true)
 
-    -- Make the Neorg filetype detectable through `vim.filetype`.
-    -- TODO: Make a PR to Neovim to natively support the org and norg
-    -- filetypes.
+    -- TODO(vhyrro): Remove this after Neovim 0.10, where `norg` files will be
+    -- detected automatically.
     vim.filetype.add({
         extension = {
             norg = "norg",
         },
     })
 
-    -- If the file we have entered has a .norg extension
+    -- If the file we have entered has a `.norg` extension:
     if vim.fn.expand("%:e") == "norg" or not config.user_config.lazy_loading then
-        -- Then boot up the environment
+        -- Then boot up the environment.
         neorg.org_file_entered(false)
     else
-        -- Else listen for a BufReadPost event and fire up the Neorg environment
+        -- Else listen for a BufReadPost event for `.norg` files and fire up the Neorg environment.
         vim.cmd([[
             autocmd BufAdd *.norg ++once :lua require('neorg').org_file_entered(false)
             command! -nargs=* NeorgStart delcommand NeorgStart | lua require('neorg').org_file_entered(true, <q-args>)
@@ -45,8 +46,8 @@ function neorg.setup(cfg)
 end
 
 --- This function gets called upon entering a .norg file and loads all of the user-defined modules.
----@param manual boolean #If true then the environment was kickstarted manually by the user
----@param arguments string? #A list of arguments in the format of "key=value other_key=other_value"
+--- @param manual boolean If true then the environment was kickstarted manually by the user.
+--- @param arguments string? A list of arguments in the format of "key=value other_key=other_value".
 function neorg.org_file_entered(manual, arguments)
     -- Extract the module list from the user config
     local module_list = config.user_config and config.user_config.load or {}
@@ -115,6 +116,9 @@ function neorg.org_file_entered(manual, arguments)
         referrer = "core",
         line_content = "",
         broadcast = true,
+        buffer = vim.api.nvim_get_current_buf(),
+        window = vim.api.nvim_get_current_win(),
+        mode = vim.fn.mode(),
     })
 
     -- Sometimes external plugins prefer hooking in to an autocommand
@@ -124,7 +128,7 @@ function neorg.org_file_entered(manual, arguments)
 end
 
 --- Returns whether or not Neorg is loaded
----@return boolean
+--- @return boolean
 function neorg.is_loaded()
     return config.started
 end

lua/neorg/core/callbacks.lua

@@ -1,25 +1,29 @@
---[[
-    Neorg User Callbacks File
-    User callbacks are ways for the user to directly interact with Neorg and respond on certain events.
---]]
+--- @brief [[
+--- Defines user callbacks - ways for the user to directly interact with Neorg and respon on certain events.
+--- @brief ]]
 
+--- @module "neorg.core.modules"
+
+--- @class neorg.callbacks
 local callbacks = {
+    ---@type table<string, { [1]: fun(event: neorg.event, content: table|any), [2]?: fun(event: neorg.event): boolean }>
     callback_list = {},
 }
 
---- Triggers a new callback to execute whenever an event of the requested type is executed
----@param event_name string #The full path to the event we want to listen on
----@param callback fun(event, content) #The function to call whenever our event gets triggered
----@param content_filter fun(event) #A filtering function to test if a certain event meets our expectations
+--- Triggers a new callback to execute whenever an event of the requested type is executed.
+--- @param event_name string The full path to the event we want to listen on.
+--- @param callback fun(event: neorg.event, content: table|any) The function to call whenever our event gets triggered.
+--- @param content_filter fun(event: neorg.event): boolean # A filtering function to test if a certain event meets our expectations.
 function callbacks.on_event(event_name, callback, content_filter)
     -- If the table doesn't exist then create it
     callbacks.callback_list[event_name] = callbacks.callback_list[event_name] or {}
     -- Insert the callback and content filter
     table.insert(callbacks.callback_list[event_name], { callback, content_filter })
 end
 
---- Used internally by Neorg to call all callbacks with an event
----@param event table #An event as returned by modules.create_event()
+--- Used internally by Neorg to call all callbacks with an event.
+--- @param event neorg.event An event as returned by `modules.create_event()`
+--- @see modules.create_event
 function callbacks.handle_callbacks(event)
     -- Query the list of registered callbacks
     local callback_entry = callbacks.callback_list[event.type]

lua/neorg/core/config.lua

@@ -1,4 +1,37 @@
--- Grab OS info on startup
+--- @brief [[
+--- Defines the configuration table for use throughout Neorg.
+--- @brief ]]
+
+-- TODO(vhyrro): Make `norg_version` and `version` a `Version` class.
+
+--- @alias OperatingSystem
+--- | "windows"
+--- | "wsl"
+--- | "wsl2"
+--- | "mac"
+--- | "linux"
+
+--- @alias neorg.configuration.module { config?: table }
+
+--- @class (exact) neorg.configuration.user
+--- @field hook? fun(manual: boolean, arguments?: string)    A user-defined function that is invoked whenever Neorg starts up. May be used to e.g. set custom keybindings.
+--- @field lazy_loading? boolean                             Whether to defer loading the Neorg core until after the user has entered a `.norg` file.
+--- @field load table<string, neorg.configuration.module>    A list of modules to load, alongside their configurations.
+--- @field logger? neorg.log.configuration                   A configuration table for the logger.
+
+--- @class (exact) neorg.configuration
+--- @field arguments table<string, string>                   A list of arguments provided to the `:NeorgStart` function in the form of `key=value` pairs. Only applicable when `user_config.lazy_loading` is `true`.
+--- @field manual boolean?                                   Used if Neorg was manually loaded via `:NeorgStart`. Only applicable when `user_config.lazy_loading` is `true`.
+--- @field modules table<string, neorg.configuration.module> Acts as a copy of the user's configuration that may be modified at runtime.
+--- @field norg_version string                               The version of the file format to be used throughout Neorg. Used internally.
+--- @field os_info OperatingSystem                           The operating system that Neorg is currently running under.
+--- @field pathsep "\\"|"/"                                  The operating system that Neorg is currently running under.
+--- @field started boolean                                   Set to `true` when Neorg is fully initialized.
+--- @field user_config neorg.configuration.user              Stores the configuration provided by the user.
+--- @field version string                                    The version of Neorg that is currently active. Automatically updated by CI on every release.
+
+--- Gets the current operating system.
+--- @return OperatingSystem
 local function get_os_info()
     local os = vim.loop.os_uname().sysname:lower()
 
@@ -19,11 +52,18 @@ local function get_os_info()
         end
         return "linux"
     end
+
+    error("[neorg]: Unable to determine the currently active operating system!")
 end
 
 local os_info = get_os_info()
 
--- Configuration template
+--- Stores the configuration for the entirety of Neorg.
+--- This includes not only the user configuration (passed to `setup()`), but also internal
+--- variables that describe something specific about the user's hardware.
+--- @see neorg.setup
+---
+--- @type neorg.configuration
 local config = {
     user_config = {
         lazy_loading = false,
@@ -43,6 +83,9 @@ local config = {
 
     os_info = os_info,
     pathsep = os_info == "windows" and "\\" or "/",
+
+    hook = nil,
+    started = false,
 }
 
 return config