[doc] standard library documentation first draft

doc/api.md

@@ -296,4 +296,4 @@ Otherwise, each Node has its own module file defined in the [ast/](../ast) direc
 
 
 ---
-_file generated at 2024-05-28T16:12:56Z_
+_file generated at 2024-06-01T11:51:03Z_

doc/gendocs.lua

@@ -65,23 +65,14 @@ local function extract_block_title(line)
 	return title
 end
 
-local valid_tags = { title = true, defer = true }
+local valid_tags = { title = true, defer = true, titlelevel = true }
 local function process(content)
 	local deferred = {}
+	local titlelevel
 
+	-- process lua files
 	local out = content:gsub("{{(.-)}}", function(lua_file)
-		-- deferred doc comments
-		if lua_file:match("^:") then
-			local defer = lua_file:match("^:(.-)$")
-			if deferred[defer] then
-				local output = table.concat(deferred[defer], "\n")
-				deferred[defer] = nil
-				return output
-			else
-				return ""
-			end
-		-- lua file
-		else
+		if not lua_file:match("^:") then
 			local f = assert(io.open(lua_file, "r"))
 			local c = f:read("a")
 			f:close()
@@ -108,15 +99,18 @@ local function process(content)
 						end
 					-- end doc comment
 					else
+						local detected_indent = 0
 						if line:match("[^%s]") then
 							local indent, code = line:match("^(%s*)(.-)$")
-							if not comment_block.indent then comment_block.indent = utf8.len(indent) end
+							detected_indent = utf8.len(indent)
 							if not comment_block.title then comment_block.title = extract_block_title(code) end
 							table.insert(comment_block, ("\n_defined at line %s of [%s](%s):_ `%s`"):format(line_no, lua_file, source_link_prefix..lua_file, code))
 						end
+						if comment_block.titlelevel then titlelevel = comment_block.titlelevel end
 						if comment_block.title then
+							local level = titlelevel or base_header_level+detected_indent
 							table.insert(comment_block, 1, ("%s %s\n"):format(
-								("#"):rep(base_header_level+(comment_block.indent or 0)),
+								("#"):rep(level),
 								comment_block.title
 							))
 						end
@@ -136,13 +130,23 @@ local function process(content)
 
 			return table.concat(output, "\n")
 		end
-	end) .. ("\n---\n_file generated at %s_"):format(os.date("!%Y-%m-%dT%H:%M:%SZ"))
+	end)
 
+	-- process deferred doc comments
+	out = out:gsub("{{:(.-)}}", function(defer)
+		if deferred[defer] then
+			local output = table.concat(deferred[defer], "\n")
+			deferred[defer] = nil
+			return output
+		else
+			return ""
+		end
+	end)
 	for k in pairs(deferred) do
 		print("[warning] unused defer "..tostring(k))
 	end
 
-	return out
+	return out .. ("\n---\n_file generated at %s_"):format(os.date("!%Y-%m-%dT%H:%M:%SZ"))
 end
 
 local function generate_file(input, output)

doc/language.md

@@ -243,6 +243,20 @@ There are three ways to associate an argument to a function parameter:
 * positional arguments: the i-th argument in the argument list is associated with the i-th parameter in the function definition parameter list;
 * the assignment argument is always associated with the assignment parameter.
 
+If the function only takes a single tuple or struct as an argument, the parentheses can be omitted.
+
+```
+:$fn(x)
+
+fn[1,2,3]
+// is the same as
+fn([1,2,3])
+
+fn{1:2,3}
+// is the same as
+fn({1:2,3})
+```
+
 ##### Dynamic dispatch
 
 Anselme uses [dynamic dispatch](https://en.wikipedia.org/wiki/Dynamic_dispatch), meaning it determine which function should be called at run-time. The dispatch is performed using all of the function parameters.
@@ -776,6 +790,12 @@ For these forms, the parameters can optionally be wrapped in parentheses in case
 :$(a::is number).b
 ```
 
+### Environments
+
+Environments consist of a scope, and can be used to get, set, and define variable in a scope that isn't the current one.
+
+An environment can, for example, be obtained using `load(path)`, which returns the exported scope of the file `path`.
+
 ### Overloads
 
 Overloads consist of a list of arbitrary values. Each value should be [callable](#calling_callables).

doc/standard_library.md.template

@@ -1,17 +1,45 @@
-TODO
+This document describes the functions defined by default by Anselme. These are accessible from any Anselme script.
 
-# Variable assignment
+This document is generated automatically from the source files in [anselme/stdlib](../anselme/stdlib).
 
-TODO intro
+{{anselme/stdlib/base.lua}}
 
 {{anselme/stdlib/assignment.lua}}
 
-# Value checking
-
-TODO
-
+{{anselme/stdlib/value check.lua}}
 {{:value checking}}
 
-# Control flow
+{{anselme/stdlib/boolean.lua}}
 
-TODO
+{{anselme/stdlib/conditionals.lua}}
+{{anselme/stdlib/for.lua}}
+
+{{anselme/stdlib/number.lua}}
+
+{{anselme/stdlib/string.lua}}
+
+{{anselme/stdlib/text.lua}}
+
+{{anselme/stdlib/symbol.lua}}
+
+{{anselme/stdlib/pair.lua}}
+
+{{anselme/stdlib/structures.lua}}
+{{:structures}}
+
+{{anselme/stdlib/function.lua}}
+{{anselme/stdlib/resume.lua}}
+
+{{anselme/stdlib/script.lua}}
+
+{{anselme/stdlib/environment.lua}}
+
+{{anselme/stdlib/typed.lua}}
+
+{{anselme/stdlib/persist.lua}}
+
+{{anselme/stdlib/attached block.lua}}
+
+{{anselme/stdlib/tag.lua}}
+
+{{anselme/stdlib/wrap.lua}}