docs: minor changes and fixes

Rosettea · Dec 26, 2023 · 48ef443 · 48ef443
1 parent 85e1307
commit 48ef443
Show file tree

Hide file tree

Showing 5 changed files with 56 additions and 47 deletions.
diff --git a/api.go b/api.go
@@ -237,7 +237,7 @@ func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // cwd() -> string
-// Returns the current directory of the shell
+// Returns the current directory of the shell.
 // #returns string
 func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	cwd, _ := os.Getwd()
@@ -249,8 +249,8 @@ func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // read(prompt) -> input (string)
 // Read input from the user, using Hilbish's line editor/input reader.
 // This is a separate instance from the one Hilbish actually uses.
-// Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen).
-// #param prompt? string
+// Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs.
+// #param prompt? string Text to print before input, can be empty.
 // #returns string|nil
 func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	luaprompt := c.Arg(0)
@@ -479,8 +479,9 @@ func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 // goro(fn)
 // Puts `fn` in a Goroutine.
-// This can be used to run any function in another thread.
+// This can be used to run any function in another thread at the same time as other Lua code.
 // **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**
+// **This is a limitation of the Lua runtime.**
 // #param fn function
 func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
@@ -503,10 +504,10 @@ func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // timeout(cb, time) -> @Timer
-// Runs the `cb` function after `time` in milliseconds.
-// This creates a Timer that starts immediately.
+// Executed the `cb` function after a period of `time`.
+// This creates a Timer that starts ticking immediately.
 // #param cb function
-// #param time number
+// #param time number Time to run in milliseconds.
 // #returns Timer
 func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
@@ -529,10 +530,10 @@ func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // interval(cb, time) -> @Timer
-// Runs the `cb` function every `time` milliseconds.
-// This creates a timer that starts immediately.
+// Runs the `cb` function every specified amount of `time`.
+// This creates a timer that ticking immediately.
 // #param cb function
-// #param time number
+// #param time number Time in milliseconds.
 // #return Timer
 func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
@@ -655,10 +656,10 @@ func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // inputMode(mode)
-// Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.
+// Sets the input mode for Hilbish's line reader.
 // `emacs` is the default. Setting it to `vim` changes behavior of input to be
 // Vim-like with modes and Vim keybinds.
-// #param mode string
+// #param mode string Can be set to either `emacs` or `vim`
 func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -683,11 +684,13 @@ func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // runnerMode(mode)
-// Sets the execution/runner mode for interactive Hilbish. This determines whether
-// Hilbish wll try to run input as Lua and/or sh or only do one of either.
+// Sets the execution/runner mode for interactive Hilbish.
+// This determines whether Hilbish wll try to run input as Lua
+// and/or sh or only do one of either.
 // Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),
 // sh, and lua. It also accepts a function, to which if it is passed one
 // will call it to execute user input instead.
+// Read [about runner mode](../features/runner-mode) for more information.
 // #param mode string|function
 func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
@@ -715,7 +718,7 @@ func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // as the text for the hint. This is by default a shim. To set hints,
 // override this function with your custom handler.
 // #param line string
-// #param pos number
+// #param pos number Position of cursor in line. Usually equals string.len(line)
 /*
 #example
 -- this will display "hi" after the cursor in a dimmed color.

diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md
@@ -17,20 +17,20 @@ interfaces and functions which directly relate to shell functionality.
 |<a href="#alias">alias(cmd, orig)</a>|Sets an alias, with a name of `cmd` to another command.|
 |<a href="#appendPath">appendPath(dir)</a>|Appends the provided dir to the command path (`$PATH`)|
 |<a href="#complete">complete(scope, cb)</a>|Registers a completion handler for the specified scope.|
-|<a href="#cwd">cwd() -> string</a>|Returns the current directory of the shell|
+|<a href="#cwd">cwd() -> string</a>|Returns the current directory of the shell.|
 |<a href="#exec">exec(cmd)</a>|Replaces the currently running Hilbish instance with the supplied command.|
 |<a href="#goro">goro(fn)</a>|Puts `fn` in a Goroutine.|
 |<a href="#highlighter">highlighter(line)</a>|Line highlighter handler.|
 |<a href="#hinter">hinter(line, pos)</a>|The command line hint handler. It gets called on every key insert to|
-|<a href="#inputMode">inputMode(mode)</a>|Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.|
-|<a href="#interval">interval(cb, time) -> @Timer</a>|Runs the `cb` function every `time` milliseconds.|
+|<a href="#inputMode">inputMode(mode)</a>|Sets the input mode for Hilbish's line reader.|
+|<a href="#interval">interval(cb, time) -> @Timer</a>|Runs the `cb` function every specified amount of `time`.|
 |<a href="#multiprompt">multiprompt(str)</a>|Changes the text prompt when Hilbish asks for more input.|
 |<a href="#prependPath">prependPath(dir)</a>|Prepends `dir` to $PATH.|
 |<a href="#prompt">prompt(str, typ)</a>|Changes the shell prompt to the provided string.|
 |<a href="#read">read(prompt) -> input (string)</a>|Read input from the user, using Hilbish's line editor/input reader.|
 |<a href="#run">run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)</a>|Runs `cmd` in Hilbish's shell script interpreter.|
-|<a href="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish. This determines whether|
-|<a href="#timeout">timeout(cb, time) -> @Timer</a>|Runs the `cb` function after `time` in milliseconds.|
+|<a href="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish.|
+|<a href="#timeout">timeout(cb, time) -> @Timer</a>|Executed the `cb` function after a period of `time`.|
 |<a href="#which">which(name) -> string</a>|Checks if `name` is a valid command.|
 
 ## Static module fields
@@ -162,7 +162,7 @@ hilbish.cwd() -> string
 </a>
 </h4>
 
-Returns the current directory of the shell  
+Returns the current directory of the shell.  
 
 #### Parameters
 This function has no parameters.  
@@ -196,8 +196,9 @@ hilbish.goro(fn)
 </h4>
 
 Puts `fn` in a Goroutine.  
-This can be used to run any function in another thread.  
+This can be used to run any function in another thread at the same time as other Lua code.  
 **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**  
+**This is a limitation of the Lua runtime.**  
 
 #### Parameters
 `function` **`fn`**  
@@ -253,7 +254,7 @@ override this function with your custom handler.
 
 
 `number` **`pos`**  
-
+Position of cursor in line. Usually equals string.len(line)
 
 #### Example
 ```lua
@@ -273,13 +274,13 @@ hilbish.inputMode(mode)
 </a>
 </h4>
 
-Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.  
+Sets the input mode for Hilbish's line reader.  
 `emacs` is the default. Setting it to `vim` changes behavior of input to be  
 Vim-like with modes and Vim keybinds.  
 
 #### Parameters
 `string` **`mode`**  
-
+Can be set to either `emacs` or `vim`
 
 </div>
 
@@ -292,15 +293,15 @@ hilbish.interval(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/
 </a>
 </h4>
 
-Runs the `cb` function every `time` milliseconds.  
-This creates a timer that starts immediately.  
+Runs the `cb` function every specified amount of `time`.  
+This creates a timer that ticking immediately.  
 
 #### Parameters
 `function` **`cb`**  
 
 
 `number` **`time`**  
-
+Time in milliseconds.
 
 </div>
 
@@ -401,11 +402,11 @@ hilbish.read(prompt) -> input (string)
 
 Read input from the user, using Hilbish's line editor/input reader.  
 This is a separate instance from the one Hilbish actually uses.  
-Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen).  
+Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs.  
 
 #### Parameters
 `string` **`prompt?`**  
-
+Text to print before input, can be empty.
 
 </div>
 
@@ -438,11 +439,13 @@ hilbish.runnerMode(mode)
 </a>
 </h4>
 
-Sets the execution/runner mode for interactive Hilbish. This determines whether  
-Hilbish wll try to run input as Lua and/or sh or only do one of either.  
+Sets the execution/runner mode for interactive Hilbish.  
+This determines whether Hilbish wll try to run input as Lua  
+and/or sh or only do one of either.  
 Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),  
 sh, and lua. It also accepts a function, to which if it is passed one  
 will call it to execute user input instead.  
+Read [about runner mode](../features/runner-mode) for more information.  
 
 #### Parameters
 `string|function` **`mode`**  
@@ -459,15 +462,15 @@ hilbish.timeout(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#
 </a>
 </h4>
 
-Runs the `cb` function after `time` in milliseconds.  
-This creates a Timer that starts immediately.  
+Executed the `cb` function after a period of `time`.  
+This creates a Timer that starts ticking immediately.  
 
 #### Parameters
 `function` **`cb`**  
 
 
 `number` **`time`**  
-
+Time to run in milliseconds.
 
 </div>
 

diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md
@@ -43,7 +43,7 @@ String that a user would write for the job
 Arguments for the commands. Has to include the name of the command.
 
 `string` **`execPath`**  
-Binary to use to run the command. Does not
+Binary to use to run the command. Needs to be an absolute path.
 
 #### Example
 ```lua

diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua
@@ -69,16 +69,17 @@ function hilbish.appendPath(dir) end
 --- 
 function hilbish.complete(scope, cb) end
 
---- Returns the current directory of the shell
+--- Returns the current directory of the shell.
 function hilbish.cwd() end
 
 --- Replaces the currently running Hilbish instance with the supplied command.
 --- This can be used to do an in-place restart.
 function hilbish.exec(cmd) end
 
 --- Puts `fn` in a Goroutine.
---- This can be used to run any function in another thread.
+--- This can be used to run any function in another thread at the same time as other Lua code.
 --- **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**
+--- **This is a limitation of the Lua runtime.**
 function hilbish.goro(fn) end
 
 --- Line highlighter handler.
@@ -98,13 +99,13 @@ function hilbish.highlighter(line) end
 --- 
 function hilbish.hinter(line, pos) end
 
---- Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.
+--- Sets the input mode for Hilbish's line reader.
 --- `emacs` is the default. Setting it to `vim` changes behavior of input to be
 --- Vim-like with modes and Vim keybinds.
 function hilbish.inputMode(mode) end
 
---- Runs the `cb` function every `time` milliseconds.
---- This creates a timer that starts immediately.
+--- Runs the `cb` function every specified amount of `time`.
+--- This creates a timer that ticking immediately.
 function hilbish.interval(cb, time) end
 
 --- Changes the text prompt when Hilbish asks for more input.
@@ -127,21 +128,23 @@ function hilbish.prompt(str, typ) end
 
 --- Read input from the user, using Hilbish's line editor/input reader.
 --- This is a separate instance from the one Hilbish actually uses.
---- Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen).
+--- Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs.
 function hilbish.read(prompt) end
 
 --- Runs `cmd` in Hilbish's shell script interpreter.
 function hilbish.run(cmd, returnOut) end
 
---- Sets the execution/runner mode for interactive Hilbish. This determines whether
---- Hilbish wll try to run input as Lua and/or sh or only do one of either.
+--- Sets the execution/runner mode for interactive Hilbish.
+--- This determines whether Hilbish wll try to run input as Lua
+--- and/or sh or only do one of either.
 --- Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),
 --- sh, and lua. It also accepts a function, to which if it is passed one
 --- will call it to execute user input instead.
+--- Read [about runner mode](../features/runner-mode) for more information.
 function hilbish.runnerMode(mode) end
 
---- Runs the `cb` function after `time` in milliseconds.
---- This creates a Timer that starts immediately.
+--- Executed the `cb` function after a period of `time`.
+--- This creates a Timer that starts ticking immediately.
 function hilbish.timeout(cb, time) end
 
 --- Checks if `name` is a valid command.

diff --git a/job.go b/job.go
@@ -418,7 +418,7 @@ func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.
 // #param cmdstr string String that a user would write for the job
 // #param args table Arguments for the commands. Has to include the name of the command.
-// #param execPath string Binary to use to run the command. Does not 
+// #param execPath string Binary to use to run the command. Needs to be an absolute path.
 /*
 #example
 hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go')