From 5fca6440aa13cc4d999796f601675e039d3c6d94 Mon Sep 17 00:00:00 2001
From: Iron-E <code.iron.e@gmail.com>
Date: Thu, 27 Aug 2020 12:10:01 -0400
Subject: [PATCH] Add comments to examples

---
 examples/key-combos-manually.vim         |  8 ++++++-
 examples/key-combos-submode.vim          |  4 ++++
 examples/key-combos-supress-exit.vim     |  4 ++++
 examples/key-combos.vim                  |  2 ++
 examples/lua/key-combos-manually.lua     |  8 +++++++
 examples/lua/key-combos-submode.lua      |  5 +++++
 examples/lua/key-combos-supress-exit.lua |  6 +++++
 examples/lua/key-combos.lua              |  4 ++++
 examples/lua/layer-simple.lua            |  3 ++-
 examples/lua/layer.lua                   |  1 +
 examples/lua/prompt-callback.lua         |  5 +++++
 examples/lua/prompt-commands.lua         |  4 ++++
 examples/lua/submodes.lua                |  9 ++++++++
 examples/lua/supress-exit.lua            |  8 +++++++
 examples/prompt-callback.vim             |  3 +++
 examples/submodes.vim                    |  4 ++++
 examples/supress-exit.vim                | 28 +++++++++++-------------
 17 files changed, 89 insertions(+), 17 deletions(-)

diff --git a/examples/key-combos-manually.vim b/examples/key-combos-manually.vim
index f654db7..9d71d1c 100644
--- a/examples/key-combos-manually.vim
+++ b/examples/key-combos-manually.vim
@@ -1,5 +1,7 @@
+" Keep track of the user's input history manually.
 let s:inputHistory = []
 
+" Clear the input history if it grows too long for our usage.
 function! s:clear(indexToCheck) abort
 	if len(s:inputHistory) > a:indexToCheck
 		for i in range(len(s:inputHistory))
@@ -8,9 +10,12 @@ function! s:clear(indexToCheck) abort
 	endif
 endfunction
 
+" This is the function that will be called whenever the user presses a button.
 function! s:fooMode() abort
-	let s:inputHistory = add(s:inputHistory, nr2char(g:fooModeInput))
+	" Append to the input history, the latest button press.
+	let s:inputHistory = add(s:inputHistory, nr2char(g:fooModeInput)) " The input is a character number.
 
+	" Custom logic to test for each character index to see if it matches the 'zfo' mapping.
 	let l:index = 0
 	if s:inputHistory[0] == 'z'
 		if get(s:inputHistory, 1, v:null) == 'f'
@@ -27,4 +32,5 @@ function! s:fooMode() abort
 	call s:clear(l:index)
 endfunction
 
+" Enter the mode to begin the demo.
 lua require('libmodal').mode.enter('FOO', 's:fooMode')
diff --git a/examples/key-combos-submode.vim b/examples/key-combos-submode.vim
index f596cba..7eb0474 100644
--- a/examples/key-combos-submode.vim
+++ b/examples/key-combos-submode.vim
@@ -1,14 +1,18 @@
+" Recurse counter.
 let s:barModeRecurse = 0
 
+" Register 'z' as the map for recursing further (by calling the BarMode function again).
 let s:barModeCombos = {
 \	'z': 'BarModeEnter',
 \}
 
+" define the BarMode() function which is called whenever the user presses 'z'
 function! s:BarMode()
 	let s:barModeRecurse += 1
 	call libmodal#Enter('BAR' . s:barModeRecurse, s:barModeCombos)
 	let s:barModeRecurse -= 1
 endfunction
 
+" Call BarMode() initially to begin the demo.
 command! BarModeEnter call s:BarMode()
 execute 'BarModeEnter'
diff --git a/examples/key-combos-supress-exit.vim b/examples/key-combos-supress-exit.vim
index b5528e0..0fe429e 100644
--- a/examples/key-combos-supress-exit.vim
+++ b/examples/key-combos-supress-exit.vim
@@ -1,7 +1,11 @@
+" Register key commands and what they do.
 let s:barModeCombos = {
 \	'': 'echom "You cant exit using escape."',
 \	'q': 'let g:barModeExit = 1'
 \}
 
+" Tell the mode not to exit automatically.
 let g:barModeExit = 0
+
+" Enter the mode using the key combos created before.
 call libmodal#Enter('BAR', s:barModeCombos, 1)
diff --git a/examples/key-combos.vim b/examples/key-combos.vim
index 3009d43..8fff30d 100644
--- a/examples/key-combos.vim
+++ b/examples/key-combos.vim
@@ -1,7 +1,9 @@
+" Register key combos for splitting windows and then closing windows
 let s:barModeCombos = {
 \	'zf': 'split',
 \	'zfo': 'vsplit',
 \	'zfc': 'q'
 \}
 
+" Enter the mode using the key combos.
 call libmodal#Enter('BAR', s:barModeCombos)
diff --git a/examples/lua/key-combos-manually.lua b/examples/lua/key-combos-manually.lua
index a15858b..6e65cd0 100644
--- a/examples/lua/key-combos-manually.lua
+++ b/examples/lua/key-combos-manually.lua
@@ -1,8 +1,11 @@
+-- Imports
 local api      = vim.api
 local libmodal = require('libmodal')
 
+-- Keep track of the user's input history manually.
 local _inputHistory = {}
 
+-- Clear the input history if it grows too long for our usage.
 function _inputHistory:clear(indexToCheck)
 	if #self >= indexToCheck then
 		for i, _ in ipairs(self) do
@@ -11,11 +14,15 @@ function _inputHistory:clear(indexToCheck)
 	end
 end
 
+-- This is the function that will be called whenever the user presses a button.
 local function fooMode()
+	-- Append to the input history, the latest button press.
 	_inputHistory[#_inputHistory + 1] = string.char(
+		-- The input is a character number.
 		api.nvim_get_var('fooModeInput')
 	)
 
+	-- Custom logic to test for each character index to see if it matches the 'zfo' mapping.
 	local index = 1
 	if _inputHistory[1] == 'z' then
 		if _inputHistory[2] == 'f' then
@@ -30,4 +37,5 @@ local function fooMode()
 	_inputHistory:clear(index)
 end
 
+-- Enter the mode to begin the demo.
 libmodal.mode.enter('FOO', fooMode)
diff --git a/examples/lua/key-combos-submode.lua b/examples/lua/key-combos-submode.lua
index b661d5f..5bf57b5 100644
--- a/examples/lua/key-combos-submode.lua
+++ b/examples/lua/key-combos-submode.lua
@@ -1,14 +1,19 @@
+-- Imports
 local libmodal = require('libmodal')
 
+-- Recurse counter.
 local fooModeRecurse = 0
+-- Register 'z' as the map for recursing further (by calling the FooMode function again).
 local fooModeCombos  = {
 	['z'] = 'lua FooMode()'
 }
 
+-- define the FooMode() function which is called whenever the user presses 'z'
 function FooMode()
 	fooModeRecurse = fooModeRecurse + 1
 	libmodal.mode.enter('FOO' .. fooModeRecurse, fooModeCombos)
 	fooModeRecurse = fooModeRecurse - 1
 end
 
+-- Call FooMode() initially to begin the demo.
 FooMode()
diff --git a/examples/lua/key-combos-supress-exit.lua b/examples/lua/key-combos-supress-exit.lua
index 51f866f..9f7a018 100644
--- a/examples/lua/key-combos-supress-exit.lua
+++ b/examples/lua/key-combos-supress-exit.lua
@@ -1,8 +1,14 @@
+-- Imports
 local libmodal = require('libmodal')
+
+-- Register key commands and what they do.
 local fooModeCombos = {
 	[''] = 'echom "You cant exit using escape."',
 	['q'] = 'let g:fooModeExit = 1'
 }
 
+-- Tell the mode not to exit automatically.
 vim.api.nvim_set_var('fooModeExit', 0)
+
+-- Enter the mode using the key combos created before.
 libmodal.mode.enter('FOO', fooModeCombos, true)
diff --git a/examples/lua/key-combos.lua b/examples/lua/key-combos.lua
index df72a0b..1dc7686 100644
--- a/examples/lua/key-combos.lua
+++ b/examples/lua/key-combos.lua
@@ -1,8 +1,12 @@
+-- Imports
 local libmodal = require('libmodal')
+
+-- Register key combos for splitting windows and then closing windows
 local fooModeCombos = {
 	['zf'] = 'split',
 	['zfo'] = 'vsplit',
 	['zfc'] = 'q'
 }
 
+-- Enter the mode using the key combos.
 libmodal.mode.enter('FOO', fooModeCombos)
diff --git a/examples/lua/layer-simple.lua b/examples/lua/layer-simple.lua
index b62ada2..c0c72fc 100644
--- a/examples/lua/layer-simple.lua
+++ b/examples/lua/layer-simple.lua
@@ -1,3 +1,4 @@
+-- Imports
 local libmodal = require('libmodal')
 
 -- create a new layer.
@@ -14,7 +15,7 @@ local exitFunc = libmodal.layer.enter({
 	}
 })
 
--- the layer will deactivate in 5 seconds.
+-- The layer will deactivate in 5 seconds for this demo.
 vim.loop.new_timer():start(5000, 0, vim.schedule_wrap(
 	function() exitFunc(); print('EXITED.') end
 ))
diff --git a/examples/lua/layer.lua b/examples/lua/layer.lua
index 5d35244..034a956 100644
--- a/examples/lua/layer.lua
+++ b/examples/lua/layer.lua
@@ -1,3 +1,4 @@
+-- Imports
 local libmodal = require('libmodal')
 
 -- create a new layer.
diff --git a/examples/lua/prompt-callback.lua b/examples/lua/prompt-callback.lua
index 8ef93f3..9bca1b0 100644
--- a/examples/lua/prompt-callback.lua
+++ b/examples/lua/prompt-callback.lua
@@ -1,7 +1,11 @@
+-- Imports
 local libmodal = require('libmodal')
 local api = vim.api
+
+-- The list of commands. Providing this will allow for autocomplete.
 local commandList = {'new', 'close', 'last'}
 
+-- The function which will be called whenever the user enters a command.
 function FooMode()
 	local userInput = vim.api.nvim_get_var('fooModeInput')
 	if userInput == 'new' then
@@ -13,4 +17,5 @@ function FooMode()
 	end
 end
 
+-- Enter the prompt.
 libmodal.prompt.enter('FOO', FooMode, commandList)
diff --git a/examples/lua/prompt-commands.lua b/examples/lua/prompt-commands.lua
index dc63913..62e9355 100644
--- a/examples/lua/prompt-commands.lua
+++ b/examples/lua/prompt-commands.lua
@@ -1,8 +1,12 @@
+-- Import
 local libmodal = require('libmodal')
+
+-- Define commands through a dictionary.
 local commands = {
 	['new']   = 'tabnew',
 	['close'] = 'tabclose',
 	['last']  = 'tablast'
 }
 
+-- Begin the prompt.
 libmodal.prompt.enter('FOO', commands)
diff --git a/examples/lua/submodes.lua b/examples/lua/submodes.lua
index 0e55e3b..4347e66 100644
--- a/examples/lua/submodes.lua
+++ b/examples/lua/submodes.lua
@@ -1,11 +1,18 @@
+-- Imports
 local libmodal = require('libmodal')
+
+-- Recurse counter
 local fooModeRecurse = 1
 
+-- Function which is called whenever the user presses a button
 function FooMode()
+	-- Append to the input history, the latest button press.
 	local userInput = string.char(vim.api.nvim_get_var(
+		-- The input is a character number.
 		'foo' .. tostring(fooModeRecurse) .. 'ModeInput'
 	))
 
+	-- If the user pressed 'z', then increase the counter and recurse.
 	if userInput == 'z' then
 		fooModeRecurse = fooModeRecurse + 1
 		Enter()
@@ -13,8 +20,10 @@ function FooMode()
 	end
 end
 
+-- Function to wrap around entering the mode so it can be recursively called.
 function Enter()
 	libmodal.mode.enter('FOO' .. fooModeRecurse, FooMode)
 end
 
+-- Initially call the function to begin the demo.
 Enter()
diff --git a/examples/lua/supress-exit.lua b/examples/lua/supress-exit.lua
index ed75360..0df74fc 100644
--- a/examples/lua/supress-exit.lua
+++ b/examples/lua/supress-exit.lua
@@ -1,17 +1,25 @@
+-- Imports
 local api = vim.api
 local libmodal = require('libmodal')
 
+-- Function which is called whenever the user presses a button
 local function fooMode()
+	-- Append to the input history, the latest button press.
 	local userInput = string.char(
+		-- The input is a character number.
 		api.nvim_get_var('fooModeInput')
 	)
 
 	if userInput == '' then
 		api.nvim_command("echom 'You cant leave using <Esc>.'")
 	elseif userInput == 'q' then
+		-- If the user presses 'q', libmodal will exit the mode.
 		api.nvim_set_var('fooModeExit', true)
 	end
 end
 
+-- Tell libmodal not to exit the mode immediately.
 api.nvim_set_var('fooModeExit', 0)
+
+-- Enter the mode.
 libmodal.mode.enter('FOO', fooMode, true)
diff --git a/examples/prompt-callback.vim b/examples/prompt-callback.vim
index d2f2331..65106a9 100644
--- a/examples/prompt-callback.vim
+++ b/examples/prompt-callback.vim
@@ -1,5 +1,7 @@
+" This is the list of commands— used for auto completion.
 let s:commandList = ['new', 'close', 'last']
 
+" This function will be called whenever a command is entered.
 function! s:fooMode() abort
 	let l:userInput = g:fooModeInput
 	if userInput == 'new'
@@ -11,4 +13,5 @@ function! s:fooMode() abort
 	endif
 endfunction
 
+" You have to convert s:commandList from a Vimscript list to a lua table using luaeval().
 call luaeval("require('libmodal').prompt.enter('FOO', 's:fooMode', _A)", s:commandList)
diff --git a/examples/submodes.vim b/examples/submodes.vim
index 480fd0e..7d6e4ed 100644
--- a/examples/submodes.vim
+++ b/examples/submodes.vim
@@ -1,5 +1,7 @@
+" This is a counter.
 let s:fooModeRecurse = 1
 
+" This is a function to increase the counter every time that 'z' is pressed.
 function! s:fooMode() abort
 	let l:userInput = nr2char(g:foo{s:fooModeRecurse}ModeInput)
 
@@ -10,8 +12,10 @@ function! s:fooMode() abort
 	endif
 endfunction
 
+" This function wraps around calling libmodal so that the other function can recursively call it.
 function! s:enter() abort
 	call luaeval("require('libmodal').mode.enter('FOO'.._A, 's:fooMode')", s:fooModeRecurse)
 endfunction
 
+" Begin the recursion.
 call s:enter()
diff --git a/examples/supress-exit.vim b/examples/supress-exit.vim
index ed75360..6f95d72 100644
--- a/examples/supress-exit.vim
+++ b/examples/supress-exit.vim
@@ -1,17 +1,15 @@
-local api = vim.api
-local libmodal = require('libmodal')
+" Function which is called every time the user presses a button.
+function! s:fooMode() abort
+	let l:userInput = nr2char(g:fooModeInput)
 
-local function fooMode()
-	local userInput = string.char(
-		api.nvim_get_var('fooModeInput')
-	)
+	if l:userInput == ''
+		echom 'You cant leave using <Esc>.'
+	elseif l:userInput == 'q'
+		let g:fooModeExit = v:true
+	endif
+endfunction
 
-	if userInput == '' then
-		api.nvim_command("echom 'You cant leave using <Esc>.'")
-	elseif userInput == 'q' then
-		api.nvim_set_var('fooModeExit', true)
-	end
-end
-
-api.nvim_set_var('fooModeExit', 0)
-libmodal.mode.enter('FOO', fooMode, true)
+" Tell the mode not to exit automatically.
+let g:fooModeExit = v:false
+" Begin the mode.
+lua require('libmodal').mode.enter('FOO', 's:fooMode', true)