adding module exmaple

Author: clpi

book/lua/module/example.lua

@@ -0,0 +1,56 @@
+local word = require("word")
+
+local mod, config, util = word.mod, word.config, word.util
+
+local M = mod.create("user.example", {
+  --- @brief submodules
+  ---         child directories containing
+  ---         modules to load in tandem, relative
+  ---         to this (parent) module.
+  --- "subexample",
+  --- "pre_example",
+  --- ...
+})
+
+M.setup = function()
+  return {
+    requires = {
+      ---@brief required modules
+      ---         modules from builtin or custom
+      ---         modules that can be loaded in (same as
+      ---         if calling `require 'module'`) as a dependency
+      ---         for the module.
+      --- "ui.popup",
+      --- "edit.link",
+      --- "integration.treesitter",
+      --- ...
+    },
+    loaded = true,
+  }
+end
+
+---@class (exact) example.Config
+M.config.public = {
+  --- @brief module config
+  ---          the public facing config for this module that can be
+  ---          set by the user from its default values here.
+  --- ...
+}
+
+---@class example.Data
+M.data = {
+  --- @brief module data
+  ---          the home of the module's internal data and methods
+  ---          TODO: split up concerns
+  --- ...
+}
+
+M.load = function()
+  --- @brief module load
+  ---          a set of functions to run whenever the
+  ---          module is fist loaded upon startup.
+  ---          TODO: maybe just merge in with setup()
+  --- ...
+end
+
+return M

book/src/SUMMARY.md

@@ -26,12 +26,17 @@ Welcome -- to the `word.lua` book. I hope this helps!
   - [Keymaps](./extend/keymaps.md)
   - [Autocmds](./extend/autocmd.md)
 
+- [Modules](./modules.md)
+
+  - [Introduction](./modules/intro.md)
+
 - [Customizing](./customizing.md)
 
   - [Themes](./customizing/themes.md)
   - [Highlights](./customizing/highlights.md)
 
 - [Export](./export.md)
+
   - [Frameworks](./publish/frameworks.md)
   - [org](./export/org.md)
 
@@ -42,6 +47,7 @@ Welcome -- to the `word.lua` book. I hope this helps!
   - [Digital garden](./publish/digital_garden.md)
 
 - [Plans](./plans/index.md)
+
   - [Near](./plans/near.md)
   - [Far](./plans/far.md)
 

book/src/modules.md

@@ -0,0 +1,63 @@
+# Modules
+
+## Example custom module
+
+```lua
+local word = require("word")
+
+local mod, config, util = word.mod, word.config, word.util
+
+local M = mod.create("user.example", {
+  --- @brief submodules
+  ---         child directories containing
+  ---         modules to load in tandem, relative
+  ---         to this (parent) module.
+  --- "subexample",
+  --- "pre_example",
+  --- ...
+})
+
+M.setup = function()
+  return {
+    requires = {
+      ---@brief required modules
+      ---         modules from builtin or custom
+      ---         modules that can be loaded in (same as
+      ---         if calling `require 'module'`) as a dependency
+      ---         for the module.
+      --- "ui.popup",
+      --- "edit.link",
+      --- "integration.treesitter",
+      --- ...
+    },
+    loaded = true,
+  }
+end
+
+---@class (exact) example.Config
+M.config.public = {
+  --- @brief module config
+  ---          the public facing config for this module that can be
+  ---          set by the user from its default values here.
+  --- ...
+}
+
+---@class example.Data
+M.data = {
+  --- @brief module data
+  ---          the home of the module's internal data and methods
+  ---          TODO: split up concerns
+  --- ...
+}
+
+M.load = function()
+  --- @brief module load
+  ---          a set of functions to run whenever the
+  ---          module is fist loaded upon startup.
+  ---          TODO: maybe just merge in with setup()
+  --- ...
+end
+
+return M
+
+```

book/src/modules/intro.md

@@ -473,7 +473,7 @@ link from the word under the cursor or a visual selection (if there is one).
 M.load = function()
   mod.await("cmd", function(cmd)
     cmd.add_commands_from_table({
-      preview = {
+      link = {
         name = "link",
         subcommands = {
           update = {