Merge pull request #120 from bew/add-inline-docs

Add inline docs to most functions based on vimdoc

Author: jake-stewart

.editorconfig

@@ -0,0 +1,5 @@
+root = true
+
+[*.lua]
+indent_style = space
+indent_size = 4

doc/.gitignore

@@ -0,0 +1 @@
+tags

doc/multicursor.txt

@@ -49,40 +49,40 @@ Continue reading for a guide of how to use the default config.
         config = function()
             local mc = require("multicursor-nvim")
             mc.setup()
-    
+
             local set = vim.keymap.set
-    
+
             -- Add or skip cursor above/below the main cursor.
             set({"n", "x"}, "<up>", function() mc.lineAddCursor(-1) end)
             set({"n", "x"}, "<down>", function() mc.lineAddCursor(1) end)
             set({"n", "x"}, "<leader><up>", function() mc.lineSkipCursor(-1) end)
             set({"n", "x"}, "<leader><down>", function() mc.lineSkipCursor(1) end)
-    
+
             -- Add or skip adding a new cursor by matching word/selection
             set({"n", "x"}, "<leader>n", function() mc.matchAddCursor(1) end)
             set({"n", "x"}, "<leader>s", function() mc.matchSkipCursor(1) end)
             set({"n", "x"}, "<leader>N", function() mc.matchAddCursor(-1) end)
             set({"n", "x"}, "<leader>S", function() mc.matchSkipCursor(-1) end)
-    
+
             -- Add and remove cursors with control + left click.
             set("n", "<c-leftmouse>", mc.handleMouse)
             set("n", "<c-leftdrag>", mc.handleMouseDrag)
             set("n", "<c-leftrelease>", mc.handleMouseRelease)
-    
+
             -- Disable and enable cursors.
             set({"n", "x"}, "<c-q>", mc.toggleCursor)
-    
+
             -- Mappings defined in a keymap layer only apply when there are
             -- multiple cursors. This lets you have overlapping mappings.
             mc.addKeymapLayer(function(layerSet)
-    
+
                 -- Select a different cursor as the main one.
                 layerSet({"n", "x"}, "<left>", mc.prevCursor)
                 layerSet({"n", "x"}, "<right>", mc.nextCursor)
-    
+
                 -- Delete the main cursor.
                 layerSet({"n", "x"}, "<leader>x", mc.deleteCursor)
-    
+
                 -- Enable and clear cursors using escape.
                 layerSet("n", "<esc>", function()
                     if not mc.cursorsEnabled() then
@@ -92,7 +92,7 @@ Continue reading for a guide of how to use the default config.
                     end
                 end)
             end)
-    
+
             -- Customize how cursors look.
             local hl = vim.api.nvim_set_hl
             hl(0, "MultiCursorCursor", { reverse = true })
@@ -229,7 +229,7 @@ mc.toggleCursor()                                   *multicursor-toggleCursor*
 
 
 mc.lineAddCursor(direction)                        *multicursor-lineAddCursor*
-    Add a cursor above or below the the main cursor, skipping empty lines,
+    Add a cursor above or below the main cursor, skipping empty lines,
     specified by `direction`.
 
     Usage example: >lua
@@ -390,7 +390,7 @@ mc.hasCursors()                                       *multicursor-hasCursors*
 
 
 mc.deleteCursor()                                   *multicursor-deleteCursor*
-    Delete the main cursor.
+    Delete the main cursor, the main cursor is now the previous cursor.
 
     Usage example: >lua
         vim.keymap.set({"n", "v"}, "<leader>x", mc.deleteCursor)
@@ -439,18 +439,23 @@ mc.alignCursors()                                   *multicursor-alignCursors*
 <
 
 mc.splitCursors()                                   *multicursor-splitCursors*
-    Split visual selections with a regex separator. For example, visually
-    selecting "a,b,c,d" and splitting with "," will create four cursors, one
-    on each letter.
+    Interactively ask for a regex separator, split every visual selections
+    with the regex separator. To be used in visual/select mode only.
+
+    For example, visually selecting "ab,cd,ef,gh" and splitting with "," will
+    create four cursors, each selecting a group of letters.
 
     Usage example: >lua
         vim.keymap.set("v", "S", mc.splitCursors)
 <
 
 mc.matchCursors()                                   *multicursor-matchCursors*
-    Match a pattern over a visual selection, creating a new cursor for each
-    match. For example, visually selecting "foo bar foo" and matching with
-    "foo" will create two cursors, one on each "foo".
+    Interactively ask for a pattern, add a cursor for each match of this
+    pattern over every visual selections.
+    To be used in visual/select mode only.
+
+    For example, visually selecting "foo bar foo" and matching with "foo" will
+    create two cursors, one on each "foo".
 
     Usage example: >lua
         vim.keymap.set("v", "M", mc.matchCursors)
@@ -529,20 +534,23 @@ mc.sequenceDecrement()                         *multicursor-sequenceDecrement*
 <
 
 mc.addCursorOperator()                         *multicursor-addCursorOperator*
-    Takes a motion and adds a cursor for each line. For example, if it is
-    mapped to `ga`, then typing `gaip` will add a cursor for every line in
-    the current paragraph.
+    Takes a motion and adds a cursor for every lines.
+
+    For example, if it is mapped to `ga`, then typing `gaip` will add a cursor
+    for every line in the current paragraph.
 
     Usage example: >lua
         vim.keymap.set("n", "ga", mc.addCursorOperator)
 <
 
 mc.operator(opts?)                                      *multicursor-operator*
     Adds a cursor for every match found in a region. The text to match is
-    given by a motion, and the region is given by a second motion. For
-    example, if mapped to `<leader>m` then `<leader>miwap` will find every
-    match within the paragraph of the text contained within `iw`. If called
-    from visual mode, the selection becomes the first motion's target text.
+    given by a motion, and the region is given by a second motion.
+
+    For example, if mapped to `<leader>m` then `<leader>miwap` will find every
+    match within the paragraph of the text contained within `iw`.
+    If called from visual mode, the selection becomes the first motion's
+    target text.
 
     Usage example: >lua
         vim.keymap.set({ "x", "n" }, "<leader>m", mc.operator)
@@ -636,7 +644,7 @@ mc.disableCursors()                               *multicursor-disableCursors*
 
 
 mc.enableCursors()                                 *multicursor-enableCursors*
-    Unlocks the cursors from moving.
+    Unlocks disabled cursors, currently active cursors will be discarded.
 
     Usage example: >lua
         vim.keymap.set({"n", "v"}, "<c-q>", mc.enableCursors)
@@ -673,9 +681,10 @@ mc.feedkeys({keys}, {opts?})                            *multicursor-feedkeys*
 
 
 mc.addKeymapLayer(callback)                       *multicursor-addKeymapLayer*
-    Calls the `callback` when there are multiple cursors. Any mappings set
-    with the provided function are automatically removed once multicursor
-    ends.
+    Registers a keymap layer callback.
+    It will be called when a buffer has cursors, any mappings set with the
+    provided function (similar to `vim.keymap.set`) will be automatically
+    removed once multicursor ends.
 
     Usage example: >lua
         mc.addKeymapLayer(function(layerSet)
@@ -1290,6 +1299,17 @@ Cursor:setRedoChangePos(pos)             *multicursor-cursor-setRedoChangePos*
       • |multicursor-types-Pos|
 
 
+Cursor:setUndoChangePos(pos)             *multicursor-cursor-setUndoChangePos*
+    Sets the position of the undo position marker.
+
+    Parameters: ~
+      • {pos} (`Pos`) new position cursor should have when undoing.
+
+    See also: ~
+      • |multicursor-types-SimplePos|
+      • |multicursor-types-Pos|
+
+
 Cursor:registerUndo()                        *multicursor-cursor-registerUndo*
     Registers this cursor so that its original position is restored upon undo.
 
@@ -1389,9 +1409,10 @@ Cursor:enable()                                    *multicursor-cursor-enable*
 
 
 Cursor:feedkeys(keys, opts?)                     *multicursor-cursor-feedkeys*
-    Makes the cursor perform a command/commands. For example,
-    `cursor:feedkeys('dw')` will delete a word. By default, keys are not
-    remapped and keycodes are not parsed.
+    Makes the cursor perform a command/commands.
+
+    For example, `cursor:feedkeys('dw')` will delete a word. By default, keys
+    are not remapped and keycodes are not parsed.
 
     Parameters: ~
       • {keys} (`string`) string representing a command

lua/multicursor-nvim/core.lua

@@ -5,36 +5,44 @@ local snippetManager = require("multicursor-nvim.snippet-manager")
 local TERM_CODES = require("multicursor-nvim.term-codes")
 
 local core = {
+    --- @type boolean Whether there is an action in progress (to prevent nested action calls)
     performingAction = false,
 }
 
---- Calls callback for each cursor with old mode, new mode
---- whenever mode is changed
---- @param callback function(cursor: Cursor, oldMode: string, newMode: string)
+--- Registers a cursor callback.
+--- It will be called for each cursor whenever mode is changed with old mode, new mode.
+--- @param callback fun(cursor: mc.Cursor, oldMode: string, newMode: string)
 function core.onModeChanged(callback)
-    return inputManager:onModeChanged(callback)
+    inputManager:onModeChanged(callback)
 end
 
+--- Registers a safe state callback.
+--- It will be called whenever the input manager is in a safe state.
+--- @param callback fun(info: mc.SafeStateInfo)
 function core.onSafeState(callback)
-    return inputManager:onSafeState(callback)
+    inputManager:onSafeState(callback)
 end
 
---- @param callback fun(set: KeymapSetCallback)
+--- Registers a keymap layer callback.
+--- It will be called when a buffer has cursors, any mappings set with the provided function
+--- (similar to `vim.keymap.set`) will be automatically removed once multicursor ends.
+--- @param callback fun(set: mc.KeymapSetterFunc)
 function core.addKeymapLayer(callback)
-    return inputManager:addKeymapLayer(callback)
+    inputManager:addKeymapLayer(callback)
 end
 
---- @param callback fun(set: KeymapSetCallback)
+--- Removes a previously registered keymap layer callback.
+--- @param callback fun(set: mc.KeymapSetterFunc)
 function core.removeKeymapLayer(callback)
-    return inputManager:removeKeymapLayer(callback)
+    inputManager:removeKeymapLayer(callback)
 end
 
---- @class MultiCursorOpts
+--- @class mc.MultiCursorOpts
 --- @field signs? string[] | nil,
---- @field shallowUndo? boolean
---- @field hlsearch? boolean
+--- @field shallowUndo? boolean  (default: false)
+--- @field hlsearch? boolean Whether to keep hlsearch for main cursor after a cursor action (default: false)
 
---- @param opts? MultiCursorOpts
+--- @param opts? mc.MultiCursorOpts
 function core.setup(opts)
     opts = opts or {}
 
@@ -67,6 +75,8 @@ function core.setup(opts)
     })
 end
 
+--- @param direction -1|1
+--- @param key string
 local function jump(direction, key)
     inputManager:performAction(function()
         if cursorManager:hasCursors() then
@@ -77,15 +87,22 @@ local function jump(direction, key)
     end)
 end
 
+--- Go to the newer cursor position in jump list.
+--- Behaves identically to `<C-i>` except it syncs up the cursors.
+--- This action is automatically mapped to `<C-i>` unless a mapping already exists.
 function core.jumpForward()
     jump(1, TERM_CODES.CTRL_I)
 end
 
+--- Go to the older cursor position in jump list.
+--- Behaves identically to `<C-o>` except it syncs up the all the cursors.
+--- This action is automatically mapped to `<C-o>` unless a mapping already exists.
 function core.jumpBackward()
     jump(-1, TERM_CODES.CTRL_O)
 end
 
---- @param callback fun(ctx: CursorContext)
+--- Perform a complex action using the |multicursor-api|.
+--- @param callback fun(ctx: mc.CursorContext) Function to execute with multicursor context
 function core.action(callback)
     if core.performingAction then
         error("An action is already being performed")
@@ -94,7 +111,7 @@ function core.action(callback)
     inputManager:performAction(function()
         local mode = vim.fn.mode()
         if mode == "i" or mode == "R" then
-            callback() --- @diagnostic disable-line
+            callback() --- @diagnostic disable-line: missing-parameter
         else
             cursorManager:action(callback, { excludeMainCursor = false })
             inputManager:clear()
@@ -103,7 +120,10 @@ function core.action(callback)
     core.performingAction = false
 end
 
---- @param keys string
+--- Use instead of `vim.fn.feedkeys()` or `vim.api.nvim_feedkeys()` in
+--- multicursor mappings to avoid bugs.
+---
+--- @param keys string String representing a command
 --- @param opts? { remap?: boolean, keycodes?: boolean }
 function core.feedkeys(keys, opts)
     opts = opts or {}
@@ -121,23 +141,33 @@ function core.hasCursors()
     return cursorManager:hasCursors()
 end
 
+--- Returns whether the cursors are locked from moving.
 --- @return boolean
 function core.cursorsEnabled()
     return cursorManager:cursorsEnabled()
 end
 
+--- Returns the total number of cursors.
+--- There is always at least one cursor (the main cursor).
+--- @return integer
 function core.numCursors()
     return cursorManager:numCursors()
 end
 
+--- Returns number of enabled cursors.
+--- There is always at least one enabled cursor (the main cursor).
+--- @return integer
 function core.numEnabledCursors()
     return cursorManager:numEnabledCursors()
 end
 
+--- Returns the number of disabled cursors.
+--- @return integer
 function core.numDisabledCursors()
     return cursorManager:numDisabledCursors()
 end
 
+--- Clear all cursors except the main cursor.
 function core.clearCursors()
     cursorManager:clear()
 end