feat: type sigs

Author: znotfireman

.config/docs.luau

@@ -5,7 +5,7 @@ return {
 	-- paths are assumed to start from docs
 	documentationPaths = {
 		mechanics = "reference/mechanics",
-		libraries = "reference/libraries",
+		api = "reference/api",
 	},
 
 	header = "<!-- This file was automatically @generated and should not be modified manually. -->",

.lute/refgen/filepaths.luau

@@ -2,6 +2,6 @@ local docs = require("@config/docs")
 local path = require("@std/path")
 
 return {
-	libraries = path.join(docs.directory, docs.documentationPaths.libraries),
+	api = path.join(docs.directory, docs.documentationPaths.api),
 	mechanics = path.join(docs.directory, docs.documentationPaths.mechanics),
 }

.lute/refgen/init.luau

@@ -1,4 +1,3 @@
-local pp = require("@batteries/pp")
 local docs = require("@config/docs")
 local project = require("@config/project")
 local clearDirectory = require("@scripts/lib/clearDirectory")
@@ -20,35 +19,41 @@ local raw = process.run({
 
 local model = moonwaveModel(json.deserialize(raw) :: moonwave.Extracted)
 
-clearDirectory(filepaths.libraries)
+clearDirectory(filepaths.api)
 
 local libraryNav: { { [string]: { string } } } = {}
 
-for _, library in model.libraries do
-	local libraryContents = templates.Library:gsub("{(.-)}", library :: { [string]: string })
+local function linkNames(content: string, hyperlinks: { [string]: string })
+	for name, url in hyperlinks do
+		content = string.gsub(content, "%f[%w]" .. name .. "%f[%W]", url)
+	end
+	return content
+end
+
+for _, class in model.classes do
+	local contents = string.gsub(templates.Class, "{([^{}]-)}", class :: { [string]: string })
 
-	local hyperlink = model.nameToHyperlinks[library.name]
-	model.nameToHyperlinks[library.name] = nil
-	libraryContents = libraryContents:gsub("%w*", model.nameToHyperlinks)
-	model.nameToHyperlinks[library.name] = hyperlink
+	local nameToHyperlinks = table.clone(model.nameToHyperlinks)
+	nameToHyperlinks[class.name] = nil
+	contents = linkNames(contents, nameToHyperlinks)
 
-	local index = path.join(library.outputDirectory, "index.md")
-	print("Writing library", library.name)
-	fs.createdirectory(library.outputDirectory, { makeparents = true })
-	fs.writestringtofile(index, libraryContents)
+	local index = path.join(class.directory, "index.md")
+	print("Writing api class", class.name)
+	fs.createdirectory(class.directory, { makeparents = true })
+	fs.writestringtofile(index, contents)
 
-	table.insert(libraryNav, { [library.name] = { path.format(path.join(library.outputUrl, "index.md")) } })
+	table.insert(libraryNav, { [class.name] = { path.format(path.join(class.url, "index.md")) } })
 end
 
 local zensical = fs.readfiletostring(docs.zensical)
 zensical = text.replaceSectionedBlock(
 	zensical,
 	-- json is close enough lmao
 	-- + toml breaks anyway
-	'{ "Libraries" = '
+	'{ "API" = '
 		.. json.serialize(libraryNav :: any):gsub(":", "=")
 		.. " }",
-	"# refgen: libraries start",
-	"# refgen: libraries end"
+	"# refgen: api start",
+	"# refgen: api end"
 )
 fs.writestringtofile(docs.zensical, zensical)

.lute/refgen/moonwaveModel.luau

@@ -1,13 +1,15 @@
 local docs = require("@config/docs")
 local project = require("@config/project")
+local tables = require("@libs/collections/tables")
 local text = require("@scripts/lib/text")
 local reconstructRequirePath = require("./reconstructRequirePath")
 local sourcemap = require("./sourcemap")
 local path = require("@std/path")
+local tableext = require("@std/tableext")
 local filepaths = require("./filepaths")
 local moonwave = require("./moonwave")
 
-export type Library = {
+export type Base = {
 	name: string,
 	slug: string,
 	summary: string,
@@ -17,50 +19,102 @@ export type Library = {
 	sourceLine: number,
 	importPath: string,
 
-	outputDirectory: path.path,
-	outputUrl: path.path,
+	url: path.path,
 }
 
-export type Mechanic = {}
+export type Class = Base & {
+	directory: path.path,
+	methods: { Method },
+	apiSignature: string,
+}
+
+export type Method = Base & {
+	filepath: path.path,
+	parameters: { moonwave.FunctionParameter },
+	returns: { moonwave.LuaType },
+	signature: string,
+}
 
 export type Model = {
-	libraries: { Library },
-	mechanics: { Mechanic },
+	classes: { Class },
 	sourcemapPaths: { [string]: { string } },
 	nameToUrls: { [string]: string },
 	nameToHyperlinks: { [string]: string },
 }
 
-local function modelLibrary(model: Model, library: moonwave.Class): Library
-	local sourcePath = project.source .. "/" .. library.source.path
-	local slug = string.lower(library.name)
-	local url = path.join(docs.documentationPaths.libraries, slug)
-	model.nameToUrls[library.name] = path.format(url)
-	model.nameToHyperlinks[library.name] = `<a href={text.quote("/" .. path.format(url))}>{library.name}</a>`
+local function modelLink(model: Model, name: string, url: path.path)
+	model.nameToUrls[name] = path.format(url)
+	model.nameToHyperlinks[name] = `<a href={text.quote("/" .. path.format(url))}>{name}</a>`
+end
+
+local function modelBase(model: Model, base: moonwave.Class | moonwave.Function)
+	local sourcePath = project.source .. "/" .. base.source.path
+	local slug = string.lower(base.name)
+	local url = path.join(docs.documentationPaths.api, slug)
 
 	return {
-		name = library.name,
+		name = base.name,
 		slug = slug,
-		summary = string.match(library.desc, "^[^\n]+") or "",
-		description = library.desc,
+		summary = string.match(base.desc, "^[^\n]+") or "",
+		description = base.desc,
 
 		sourcePath = sourcePath,
-		sourceLine = library.source.line,
+		sourceLine = base.source.line,
 		importPath = table.concat(
 			reconstructRequirePath(model.sourcemapPaths, sourcePath)
-				or error(`library {library.source.path} cannot be imported`),
+				or error(`{base.source.path} cannot be imported; is it included under rojo?`),
 			"/"
 		),
 
-		outputDirectory = path.join(filepaths.libraries, slug),
-		outputUrl = url,
+		url = url,
 	}
 end
 
+local function modelMethod(model: Model, class: Class, method: moonwave.Function)
+	local base = modelBase(model, method) :: Method
+	base.filepath = path.join(class.directory, base.slug)
+	base.url = path.join(class.url, base.slug)
+	base.parameters = method.params
+	base.returns = method.returns
+
+	local parameterSignature = tableext.map(base.parameters, function(p: moonwave.FunctionParameter)
+		return `{p.name}: {p.lua_type}`
+	end)
+
+	local returnTypes = tableext.map(base.returns, function(t: moonwave.LuaType)
+		return t.lua_type
+	end)
+
+	local returnBraces = if #returnTypes == 1 then "%s" else "(%s)"
+	local returnSignature = string.format(returnBraces :: any, table.concat(returnTypes, ", "))
+
+	base.signature = `({table.concat(parameterSignature, ", ")}) -> {returnSignature}`
+
+	return base
+end
+
+local function modelClass(model: Model, class: moonwave.Class): Class
+	local base = modelBase(model, class) :: Class
+	modelLink(model, base.name, base.url)
+	base.directory = path.join(filepaths.api, base.slug)
+
+	local apiSignature = {}
+
+	base.methods = tables.create(#class.functions)
+	for index, method in class.functions do
+		local methodModel = modelMethod(model, base, method)
+		base.methods[index] = methodModel
+		table.insert(apiSignature, `   {methodModel.name}: {methodModel.signature},`)
+	end
+
+	base.apiSignature = if #apiSignature > 1 then table.concat(apiSignature, "\n") else "   -- No APIs implemented."
+
+	return base
+end
+
 local function moonwaveModel(classes: { moonwave.Class })
 	local model: Model = {
-		libraries = {},
-		mechanics = {},
+		classes = {},
 		sourcemapPaths = sourcemap.process(),
 		nameToUrls = {},
 		nameToHyperlinks = {},
@@ -70,8 +124,8 @@ local function moonwaveModel(classes: { moonwave.Class })
 		local tags: { string } = class.tags or {}
 
 		for _, tag in tags do
-			if tag == "Library" then
-				table.insert(model.libraries, modelLibrary(model, class))
+			if tag == "Class" then
+				table.insert(model.classes, modelClass(model, class))
 				break
 			end
 		end

…cs/reference/libraries/mechanic/index.md .lute/refgen/templates/Class.luaudocs/reference/libraries/mechanic/index.md renamed to .lute/refgen/templates/Class.luau docs/reference/libraries/mechanic/index.md renamed to .lute/refgen/templates/Class.luau

@@ -1,17 +1,20 @@
-<!--
+return [[<!--
     This file was automatically @generated using Welcome To Hell's `refgen`. 
     As changes may be overriden, this file should not be manually modified.
 -->
 
-# Mechanic
+# {name}
 
 ```luau
-local Mechanic = require("@game/ReplicatedStorage/Libs/Mechanic")
+{name} = {
+{apiSignature}
+}
 ```
 
-
+{description}
 
 ## API
 
 {api}
 
+]]

.lute/refgen/templates/init.luau

@@ -1,6 +1,7 @@
 return {
 	ApiItem = require("@self/ApiItem"),
 	ApiList = require("@self/ApiLIst"),
+	Class = require("@self/Class"),
 	Function = require("@self/Function"),
 	FunctionParameter = require("@self/FunctionParameter"),
 	FunctionReturn = require("@self/FunctionReturn"),

docs/reference/libraries/level/index.md docs/reference/api/level/index.mddocs/reference/libraries/level/index.md renamed to docs/reference/api/level/index.md

@@ -6,7 +6,9 @@
 # Level
 
 ```luau
-local Level = require("@game/ReplicatedStorage/Libs/Level")
+Level = {
+   -- No APIs implemented.
+}
 ```
 
 Orchestrator of scripts and mechanics in levels.
@@ -15,7 +17,7 @@ Levels can be traversed by the player with mechanics, level scripts, and
 some starting positions. Alongside towers, Levels are also used to represent
 Chapters in Welcome To Hell's Campaign.
 
-This class should not be constructed by tower scripts. Many <a href="/reference/libraries/mechanic">Mechanic</a>
+This class should not be constructed by tower scripts. Many Mechanic
 methods provide a handle to a tower's Level as the last argument.
 
 ## API

docs/reference/api/scriptcollector/index.md

@@ -0,0 +1,24 @@
+<!--
+    This file was automatically @generated using Welcome To Hell's `refgen`. 
+    As changes may be overriden, this file should not be manually modified.
+-->
+
+# ScriptCollector
+
+```luau
+ScriptCollector = {
+   new: () -> (),
+   clone: (self: ScriptCollector) -> ScriptCollector,
+   collectModuleScript: (self: ScriptCollector, instance: ModuleScript) -> (),
+   collectInstance: (self: ScriptCollector, instance: Instance) -> (),
+   collectInstanceAsync: (self: ScriptCollector, instance: Instance) -> Promise,
+   collectInstancesAsync: (self: ScriptCollector, instances: { Instance }) -> Promise,
+}
+```
+
+Collects mechanic implementations from module scripts for use in levels.
+
+## API
+
+{api}
+