docs: allow linking to types on different pages, improve docs for hilbish functions

api.go

@@ -231,8 +231,9 @@ func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext(t.Runtime, rt.IntValue(int64(exitcode)), rt.StringValue(stdoutStr), rt.StringValue(stderrStr)), nil
 }
 
-// cwd()
+// cwd() -> string
 // Returns the current directory of the shell
+// --- @returns string
 func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	cwd, _ := os.Getwd()
 
@@ -444,12 +445,12 @@ func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
-// timeout(cb, time)
-// Runs the `cb` function after `time` in milliseconds
-// Returns a `timer` object (see `doc timers`).
+// timeout(cb, time) -> @Timer
+// Runs the `cb` function after `time` in milliseconds.
+// This creates a timer that starts immediately.
 // --- @param cb function
 // --- @param time number
-// --- @returns table
+// --- @returns Timer
 func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
 		return nil, err
@@ -470,12 +471,12 @@ func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, rt.UserDataValue(timer.ud)), nil
 }
 
-// interval(cb, time)
+// interval(cb, time) -> @Timer
 // Runs the `cb` function every `time` milliseconds.
-// Returns a `timer` object (see `doc timers`).
+// This creates a timer that starts immediately.
 // --- @param cb function
 // --- @param time number
-// --- @return table
+// --- @return Timer
 func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
 		return nil, err
@@ -536,9 +537,11 @@ func hlprependPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
-// which(name)
-// Checks if `name` is a valid command
+// which(name) -> string
+// Checks if `name` is a valid command.
+// Will return the path of the binary, or a basename if it's a commander.
 // --- @param name string
+// --- @returns string
 func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err

cmd/docgen/docgen.go

@@ -65,6 +65,7 @@ type tag struct {
 var docs = make(map[string]module)
 var interfaceDocs = make(map[string]module)
 var emmyDocs = make(map[string][]emmyPiece)
+var typeTable = make(map[string][]string) // [0] = parentMod, [1] = interfaces
 var prefix = map[string]string{
 	"main": "hl",
 	"hilbish": "hl",
@@ -183,6 +184,8 @@ func setupDocType(mod string, typ *doc.Type) *docPiece {
 		Properties: properties,
 	}
 
+	typeTable[strings.ToLower(typeName)] = []string{parentMod, interfaces}
+
 	return dps
 }
 
@@ -442,8 +445,9 @@ func main() {
 						// todo: get type from global table to link to
 						// other pages (hilbish page can link to hilbish.jobs#Job)
 						typName := typ[1:]
-						linkedTyp := strings.ToLower(typName) // TODO: link
-						return fmt.Sprintf(`<a href="#%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName)
+						typLookup := typeTable[strings.ToLower(typName)]
+						linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s/#%s", typLookup[0], typLookup[0] + "." + typLookup[1], strings.ToLower(typName))
+						return fmt.Sprintf(`<a href="%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName)
 					})
 					f.WriteString(fmt.Sprintf("### %s\n", htmlSig))
 					for _, doc := range dps.Doc {

docs/api/hilbish/_index.md

@@ -35,7 +35,7 @@ replacing <cmd> with the name of the command (for example `command.git`).
 `cb` must be a function that returns a table of "completion groups."
 Check `doc completions` for more information.
 
-### cwd()
+### cwd() -> string
 Returns the current directory of the shell
 
 ### exec(cmd)
@@ -60,9 +60,9 @@ override this function with your custom handler.
 ### inputMode(mode)
 Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
 
-### interval(cb, time)
+### interval(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#timer" style="text-decoration: none;">Timer</a>
 Runs the `cb` function every `time` milliseconds.
-Returns a `timer` object (see `doc timers`).
+This creates a timer that starts immediately.
 
 ### multiprompt(str)
 Changes the continued line prompt to `str`
@@ -95,10 +95,11 @@ 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.
 
-### timeout(cb, time)
-Runs the `cb` function after `time` in milliseconds
-Returns a `timer` object (see `doc timers`).
+### timeout(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#timer" style="text-decoration: none;">Timer</a>
+Runs the `cb` function after `time` in milliseconds.
+This creates a timer that starts immediately.
 
-### which(name)
-Checks if `name` is a valid command
+### which(name) -> string
+Checks if `name` is a valid command.
+Will return the path of the binary, or a basename if it's a commander.
 

docs/api/hilbish/hilbish.jobs.md

@@ -21,16 +21,16 @@ Stops the job from running.
 ### add(cmdstr, args, execPath)
 Adds a new job to the job table. Note that this does not immediately run it.
 
-### all() -> table\<<a href="#job" style="text-decoration: none;">Job</a>>
+### all() -> table\<<a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;">Job</a>>
 Returns a table of all job objects.
 
 ### disown(id)
 Disowns a job. This deletes it from the job table.
 
-### get(id) -> <a href="#job" style="text-decoration: none;">Job</a>
+### get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;">Job</a>
 Get a job object via its ID.
 
-### last() -> <a href="#job" style="text-decoration: none;">Job</a>
+### last() -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;">Job</a>
 Returns the last added job from the table.
 
 ## Types

docs/api/hilbish/hilbish.timers.md

@@ -35,11 +35,11 @@ print(t.running) // true
 - `TIMEOUT`: Constant for a timeout timer type
 
 ## Functions
-### create(type, time, callback) -> <a href="#timer" style="text-decoration: none;">Timer</a>
+### create(type, time, callback) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#timer" style="text-decoration: none;">Timer</a>
 Creates a timer that runs based on the specified `time` in milliseconds.
 The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
 
-### get(id) -> <a href="#timer" style="text-decoration: none;">Timer</a>
+### get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#timer" style="text-decoration: none;">Timer</a>
 Retrieves a timer via its ID.
 
 ## Types

emmyLuaDocs/hilbish.lua

@@ -63,6 +63,7 @@ function hilbish.appendPath(dir) end
 function hilbish.complete(scope, cb) end
 
 --- Returns the current directory of the shell
+--- @returns string
 function hilbish.cwd() end
 
 --- Replaces running hilbish with `cmd`
@@ -94,10 +95,10 @@ function hilbish.hinter(line, pos) end
 function hilbish.inputMode(mode) end
 
 --- Runs the `cb` function every `time` milliseconds.
---- Returns a `timer` object (see `doc timers`).
+--- This creates a timer that starts immediately.
 --- @param cb function
 --- @param time number
---- @return table
+--- @return Timer
 function hilbish.interval(cb, time) end
 
 --- Changes the continued line prompt to `str`
@@ -141,15 +142,17 @@ function hilbish.run(cmd, returnOut) end
 --- @param mode string|function
 function hilbish.runnerMode(mode) end
 
---- Runs the `cb` function after `time` in milliseconds
---- Returns a `timer` object (see `doc timers`).
+--- Runs the `cb` function after `time` in milliseconds.
+--- This creates a timer that starts immediately.
 --- @param cb function
 --- @param time number
---- @returns table
+--- @returns Timer
 function hilbish.timeout(cb, time) end
 
---- Checks if `name` is a valid command
+--- Checks if `name` is a valid command.
+--- Will return the path of the binary, or a basename if it's a commander.
 --- @param name string
+--- @returns string
 function hilbish.which(name) end
 
 --- Puts a job in the background. This acts the same as initially running a job.