β0.1.0 Improve type annotations

Improve readme
Add versioning

Author: gitpushjoe

configs.lua

@@ -1,7 +1,7 @@
 local utils = require("core.utils")
 local Path = require("core.path")
 
----@type { [string]: PartialConfigTable }
+---@type table<string, PartialConfigTable>
 local configs = {
 
 	DEFAULT = {

core/config.lua

@@ -75,7 +75,7 @@ Config.__name = "Config"
 Config.errors = {
 
 	--- @param list table
-	--- @return string
+	--- @return string errmsg
 	missing_item_in_note_schema_list = function(list, idx)
 		return "Missing "
 			.. (#list <= 1 and "open-tag" or "close-tag")
@@ -84,7 +84,7 @@ Config.errors = {
 			.. "]."
 	end,
 
-	--- @return string
+	--- @return string errmsg
 	root_reserved = function()
 		return "Cannot use "
 			.. "ROOT"
@@ -98,7 +98,8 @@ Config.errors = {
 }
 
 --- @param config_table PartialConfigTable
---- @return Config?, string?
+--- @return Config? config
+--- @return string? errmsg
 function Config:new(config_table)
 	self = {}
 	--- @cast self Config

core/context.lua

@@ -90,7 +90,8 @@ Context.errors = {
 ---@param text_stream Stream
 ---@param preserve boolean
 ---@param ansi_enabled boolean
----@return Context?, string?
+---@return Context? ctx
+---@return string? errmsg
 function Context:new(
 	config,
 	src_path,

core/fold.lua

@@ -14,21 +14,21 @@ M.__name = "fold"
 M.errors = {
 
 	---@param section Section?
-	---@return string
+	---@return string errmsg
 	unterminated_section = function(section)
 		return "Unterminated section: " .. (tostring(section) or "nil")
 	end,
 
 	---@param line number
-	---@return string
+	---@return string errmsg
 	inconsistent_indent = function(line)
 		return "Inconsistent indent on line " .. line
 	end,
 
 	---@param retry_count number
 	---@param section Section?
 	---@param is_local boolean?
-	---@return string
+	---@return string errmsg
 	maximum_retry_count = function(retry_count, section, is_local)
 		return "Maximum "
 			.. (is_local and "local " or "")
@@ -39,7 +39,7 @@ M.errors = {
 	end,
 
 	---@param path Path
-	---@return string
+	---@return string errmsg
 	path_should_not_be_directory = function(path)
 		return "`config.resolve_path` returned directory-type Path ("
 			.. path:escaped()
@@ -48,14 +48,14 @@ M.errors = {
 
 	---@param path string
 	---@param section Section?
-	---@return string
+	---@return string errmsg
 	cannot_write = function(path, section)
 		return "Cannot write to path " .. path .. "\n" .. tostring(section)
 	end,
 
 	---@param command string
 	---@param err string?
-	---@return string
+	---@return string errmsg
 	command_failed = function(command, err)
 		return "Failed to execute command: "
 			.. command
@@ -64,14 +64,15 @@ M.errors = {
 	end,
 
 	---@param path string
-	---@return string
+	---@return string errmsg
 	expected_file_to_be_writable = function(path)
 		return "Expected file " .. tostring(path) .. " to be writable"
 	end,
 }
 
 ---@param ctx Context
----@return Section?, string?
+---@return Section? section
+---@return string? errmsg
 M.parse = function(ctx)
 	local curr_section, err = Section:new(
 		0,
@@ -160,7 +161,8 @@ end
 
 ---@param section_root Section
 ---@param ctx Context
----@return nil, string?
+---@return nil
+---@return string? errmsg
 M.prepare = function(section_root, ctx)
 	---@type { [string]: Section }
 	local created_files = {}
@@ -265,7 +267,8 @@ end
 ---@param section_root Section
 ---@param ctx Context
 ---@param is_dry_run boolean?
----@return Plan?, string?
+---@return Plan? plan
+---@return string? errmsg
 M.execute = function(section_root, ctx, is_dry_run)
 	is_dry_run = is_dry_run or false
 	local io = ctx.io
@@ -308,7 +311,7 @@ M.execute = function(section_root, ctx, is_dry_run)
 	---@param lines string[]
 	---@param path Path
 	---@param is_overwrite boolean?
-	---@return string?
+	---@return string? errmsg
 	local function write(handle, lines, path, is_overwrite)
 		is_overwrite = is_overwrite or false
 		created_or_modified_paths[tostring(path)] = 1
@@ -325,7 +328,7 @@ M.execute = function(section_root, ctx, is_dry_run)
 	end
 
 	---@param directory Path
-	---@return string?
+	---@return string? errmsg
 	local function mkdir(directory)
 		created_or_modified_paths[tostring(directory)] = 1
 		if not is_dry_run then

core/parser.lua

@@ -1,6 +1,6 @@
 local validate = require("core.validate")
 
----@alias Equivalences { [string]: EquivalenceClass|string|nil }
+---@alias Equivalences table<string, EquivalenceClass|string|nil>
 
 ---@class (exact) EquivalenceClass
 ---@field equivalences string[]

core/path.lua

@@ -35,7 +35,8 @@ end
 ---@param path string|string[]
 ---`allow_relative` IS INTENDED FOR INTERNAL USE ONLY.
 ---@param allow_relative boolean?
----@return Path?, string?
+---@return Path? path
+---@return string? errmsg
 function Path:new(path, allow_relative)
 	self = {}
 	setmetatable(self, Path)
@@ -137,7 +138,7 @@ end
 --- assert(path:pop_directory() == "baz")
 --- assert(path == Path:new("/foo/"))
 --- ```
---- @return string?
+--- @return string? errmsg
 function Path:pop_directory()
 	handle_is_void(self)
 	if #self.parts <= 2 then
@@ -200,7 +201,7 @@ end
 --- assert(path == Path:new("/foo/"))
 --- ```
 --- @param filename string
---- @return string
+--- @return string old_filename
 function Path:set_filename(filename)
 	handle_is_void(self)
 	if #self.parts < 1 then
@@ -252,7 +253,7 @@ end
 --- assert(Path:new("/foo/bar"):join("./baz") == Path:new("/foo/baz"))
 --- ```
 --- @param path string
---- @return Path?
+--- @return Path? new_path
 --- @return string? errmsg
 function Path:join(path)
 	local err = validate.types("Path:join", { { path, "string", "path" } })

core/section.lua

@@ -55,7 +55,8 @@ Section.ROOT = "ROOT"
 ---@param children Section[]
 ---@param parent Section?
 ---@param indent string?
----@return Section?, string?
+---@return Section? section
+---@return string? errmsg
 function Section:new(
 	id,
 	type,
@@ -205,7 +206,7 @@ function Section:type_name_is(name)
 	return name == self:type_name()
 end
 
----@return string?
+---@return string
 function Section:__tostring()
 	return "Section {"
 		.. '\n\ttype = {"'

core/validate.lua

@@ -9,7 +9,7 @@ M.RETVAL = "RETVAL"
 ---@param expected_type string
 ---@param actual string
 ---@overload fun(function_name: string, triplet: {[1]: any, [2]: string, [3]: string?}): string
----@return string
+---@return string errmsg
 M.invalid_type_error = function(function_name, arg_name, expected_type, actual)
 	arg_name = arg_name or M.RETVAL
 	if type(arg_name) == type({}) then
@@ -36,6 +36,7 @@ end
 ---@param expected_class table
 ---@param actual any
 ---@overload fun(function_name: string, triplet: {[1]: any, [2]: table, [3]: string?}): string
+---@return string
 M.invalid_instance_error = function(
 	function_name,
 	arg_name,
@@ -72,7 +73,7 @@ end
 
 ---@param function_name string
 ---@param data {[1]: any, [2]: string, [3]: string?}[]
----@return string?
+---@return string? errmsg
 M.types = function(function_name, data)
 	for _, item in ipairs(data) do
 		local elem = item[1]
@@ -105,7 +106,7 @@ end
 ---@param list any[]
 ---@param arg_name string
 ---@param expected_type string
----@return string?
+---@return string? errmsg
 M.types_in_list = function(function_name, list, arg_name, expected_type)
 	arg_name = arg_name or M.RETVAL
 	local err = M.types(function_name, { { list, "table", arg_name } })
@@ -131,7 +132,7 @@ end
 
 ---@param function_name string
 ---@param data {[1]: any, [2]: table, [3]: string?}[]
----@return string?
+---@return string? errmsg
 M.are_instances = function(function_name, data)
 	for _, item in ipairs(data) do
 		if not item[1] then

core/version.lua

@@ -0,0 +1 @@
+return "β0.1.0"

examples/bible/configs.lua

@@ -1,7 +1,7 @@
 local Path = require("core.path")
 local utils = require("core.utils")
 
----@type { [string]: PartialConfigTable }
+---@type table<string, PartialConfigTable>
 local configs = {
 
 	bible = {