Adds support for arbitrary doc tags

docgen.lua

@@ -1,12 +1,14 @@
 --[=[
-@i?c ClassName [x base_1 x base_2 ... x base_n]
+@c ClassName [x base_1 x base_2 ... x base_n]
+@t tag (one of: ui, abc)
 @p parameterName type
 @op optionalParameterName type
 @d class description+
 ]=]
 
 --[=[
-@s?m methodName
+@m methodName
+@t tag (one of: static)
 @p parameterName type
 @op optionalParameterName type
 @r return
@@ -39,10 +41,16 @@ local function match(s, pattern) -- only useful for one capture
 	return assert(s:match(pattern), s)
 end
 
-local function gmatch(s, pattern) -- only useful for one capture
+local function gmatch(s, pattern, hash) -- only useful for one capture
 	local tbl = {}
-	for v in s:gmatch(pattern) do
-		insert(tbl, v)
+	if hash then
+		for k in s:gmatch(pattern) do
+			tbl[k] = true
+		end
+	else
+		for v in s:gmatch(pattern) do
+			insert(tbl, v)
+		end
 	end
 	return tbl
 end
@@ -56,11 +64,11 @@ local function matchComments(s)
 end
 
 local function matchClassName(s)
-	return match(s, '@i?c (%S+)')
+	return match(s, '@c (%S+)')
 end
 
 local function matchMethodName(s)
-	return match(s, '@s?m (%S+)')
+	return match(s, '@m (%S+)')
 end
 
 local function matchDescription(s)
@@ -75,6 +83,10 @@ local function matchReturns(s)
 	return gmatch(s, '@r (%S+)')
 end
 
+local function matchTags(s)
+	return gmatch(s, '@t (%S+)', true)
+end
+
 local function matchProperty(s)
 	local a, b, c = s:match('@p (%S+) (%S+) (.+)')
 	return {
@@ -98,6 +110,7 @@ local function matchMethod(s)
 		desc = matchDescription(s),
 		parameters = matchParameters(s),
 		returnTypes = matchReturns(s),
+		tags = matchTags(s),
 	}
 end
 
@@ -113,12 +126,12 @@ local function newClass()
 		properties = {},
 	}
 
-	local function init(s, userInitialized)
+	local function init(s)
 		class.name = matchClassName(s)
 		class.parents = matchParents(s)
 		class.desc = matchDescription(s)
 		class.parameters = matchParameters(s)
-		class.userInitialized = userInitialized
+		class.tags = matchTags(s)
 		assert(not docs[class.name], 'duplicate class: ' .. class.name)
 		docs[class.name] = class
 	end
@@ -136,12 +149,9 @@ for f in coroutine.wrap(scan), './libs' do
 		local t = matchType(s)
 		if t == 'c' then
 			initClass(s)
-		elseif t == 'ic' then
-			initClass(s, true)
-		elseif t == 'sm' then
-			insert(class.statics, matchMethod(s))
 		elseif t == 'm' then
-			insert(class.methods, matchMethod(s))
+			local method = matchMethod(s)
+			insert(method.tags.static and class.statics or class.methods, method)
 		elseif t == 'p' then
 			insert(class.properties, matchProperty(s))
 		end
@@ -244,7 +254,7 @@ for _, class in pairs(docs) do
 
 	f:write(class.desc, '\n\n')
 
-	if class.userInitialized then
+	if class.tags.ui then
 		writeHeading(f, 'Constructor')
 		f:write('### ', class.name)
 		writeParameters(f, class.parameters)

libs/client/Client.lua

@@ -1,5 +1,6 @@
 --[=[
-@ic Client x Emitter
+@c Client x Emitter
+@t ui
 @op options table
 @d The main point of entry into a Discordia application. All data relevant to
 Discord is accessible through a client instance or its child objects after a

libs/containers/abstract/Channel.lua

@@ -1,7 +1,7 @@
 --[=[
 @c Channel x Snowflake
-@d Abstract base class that defines the base methods and properties for all
-Discord channel types.
+@t abc
+@d Defines the base methods and properties for all Discord channel types.
 ]=]
 
 local Snowflake = require('containers/abstract/Snowflake')

libs/containers/abstract/Container.lua

@@ -1,8 +1,9 @@
 --[=[
 @c Container
-@d Abstract base class that defines the base methods and properties for all
-Discord objects and structures. Container classes are constructed internally
-with information received from Discord and should never be manually constructed.
+@t abc
+@d Defines the base methods and properties for all Discord objects and
+structures. Container classes are constructed internally with information
+received from Discord and should never be manually constructed.
 ]=]
 
 local json = require('json')

libs/containers/abstract/GuildChannel.lua

@@ -1,7 +1,7 @@
 --[=[
 @c GuildChannel x Channel
-@d Abstract base class that defines the base methods and properties for all
-Discord guild channels.
+@t abc
+@d Defines the base methods and properties for all Discord guild channels.
 ]=]
 
 local json = require('json')

libs/containers/abstract/Snowflake.lua

@@ -1,7 +1,8 @@
 --[=[
 @c Snowflake x Container
-@d Abstract base class that defines the base methods and/or properties for all
-Discord objects that have a Snowflake ID.
+@t abc
+@d Defines the base methods and/or properties for all Discord objects that have
+a Snowflake ID.
 ]=]
 
 local Date = require('utils/Date')

libs/containers/abstract/TextChannel.lua

@@ -1,7 +1,7 @@
 --[=[
 @c TextChannel x Channel
-@d Abstract base class that defines the base methods and properties for all
-Discord text channels.
+@t abc
+@d Defines the base methods and properties for all Discord text channels.
 ]=]
 
 local pathjoin = require('pathjoin')

libs/containers/abstract/UserPresence.lua

@@ -1,9 +1,10 @@
 --[=[
 @c UserPresence x Container
-@d Abstract base class that defines the base methods and/or properties for
-classes that represent a user's current presence information. Note that any
-method or property that exists for the User class is also available in the
-UserPresence class and its subclasses.
+@t abc
+@d Defines the base methods and/or properties for classes that represent a
+user's current presence information. Note that any method or property that
+exists for the User class is also available in the UserPresence class and its
+subclasses.
 ]=]
 
 local null = require('json').null

libs/utils/Clock.lua

@@ -1,5 +1,6 @@
 --[=[
-@ic Clock x Emitter
+@c Clock x Emitter
+@t ui
 @d Used to periodically execute code according to the ticking of the system clock instead of arbitrary interval.
 ]=]
 

libs/utils/Color.lua

@@ -1,5 +1,6 @@
 --[=[
-@ic Color
+@c Color
+@t ui
 @p value number
 @d Wrapper for 24-bit colors packed as a decimal value. See the static constructors for more information.
 ]=]
@@ -83,7 +84,8 @@ function Color:__div(other)
 end
 
 --[=[
-@sm fromHex
+@m fromHex
+@t static
 @p hex string
 @r Color
 @d Constructs a new Color object from a hexadecimal string. The string may or may
@@ -94,7 +96,8 @@ function Color.fromHex(hex)
 end
 
 --[=[
-@sm fromRGB
+@m fromRGB
+@t static
 @p r number
 @p g number
 @p b number
@@ -153,7 +156,8 @@ local function toHue(r, g, b)
 end
 
 --[=[
-@sm fromHSV
+@m fromHSV
+@t static
 @p h number
 @p s number
 @p v number
@@ -172,7 +176,8 @@ function Color.fromHSV(h, s, v)
 end
 
 --[=[
-@sm fromHSL
+@m fromHSL
+@t static
 @p h number
 @p s number
 @p l number

libs/utils/Date.lua

@@ -1,5 +1,6 @@
 --[=[
-@ic Date
+@c Date
+@t ui
 @op seconds number
 @op microseconds number
 @d Represents a single moment in time and provides utilities for converting to
@@ -125,7 +126,8 @@ function Date:__sub(other)
 end
 
 --[=[
-@sm parseISO
+@m parseISO
+@t static
 @p str string
 @r number
 @r number
@@ -145,7 +147,8 @@ function Date.parseISO(str)
 end
 
 --[=[
-@sm parseHeader
+@m parseHeader
+@t static
 @p str string
 @r number
 @d Converts an RFC 2822 string (an HTTP Date header) into a Unix time in seconds.
@@ -161,7 +164,8 @@ function Date.parseHeader(str)
 end
 
 --[=[
-@sm parseSnowflake
+@m parseSnowflake
+@t static
 @p id string
 @r number
 @d Converts a Discord Snowflake ID into a Unix time in seconds. Additional
@@ -173,7 +177,8 @@ function Date.parseSnowflake(id)
 end
 
 --[=[
-@sm parseTable
+@m parseTable
+@t static
 @p tbl table
 @r number
 @d Interprets a Lua date table as a local time and converts it to a Unix time in
@@ -184,7 +189,8 @@ function Date.parseTable(tbl)
 end
 
 --[=[
-@sm parseTableUTC
+@m parseTableUTC
+@t static
 @p tbl table
 @r number
 @d Interprets a Lua date table as a UTC time and converts it to a Unix time in
@@ -195,7 +201,8 @@ function Date.parseTableUTC(tbl)
 end
 
 --[=[
-@sm fromISO
+@m fromISO
+@t static
 @p str string
 @r Date
 @d Constructs a new Date object from an ISO 8601 string. Equivalent to
@@ -206,7 +213,8 @@ function Date.fromISO(str)
 end
 
 --[=[
-@sm fromHeader
+@m fromHeader
+@t static
 @p str string
 @r Date
 @d Constructs a new Date object from an RFC 2822 string. Equivalent to
@@ -217,7 +225,8 @@ function Date.fromHeader(str)
 end
 
 --[=[
-@sm fromSnowflake
+@m fromSnowflake
+@t static
 @p id string
 @r Date
 @d Constructs a new Date object from a Discord/Twitter Snowflake ID. Equivalent to
@@ -228,7 +237,8 @@ function Date.fromSnowflake(id)
 end
 
 --[=[
-@sm fromTable
+@m fromTable
+@t static
 @p tbl table
 @r Date
 @d Constructs a new Date object from a Lua date table interpreted as a local time.
@@ -239,7 +249,8 @@ function Date.fromTable(tbl)
 end
 
 --[=[
-@sm fromTableUTC
+@m fromTableUTC
+@t static
 @p tbl table
 @r Date
 @d Constructs a new Date object from a Lua date table interpreted as a UTC time.
@@ -250,7 +261,8 @@ function Date.fromTableUTC(tbl)
 end
 
 --[=[
-@sm fromSeconds
+@m fromSeconds
+@t static
 @p s number
 @r Date
 @d Constructs a new Date object from a Unix time in seconds.
@@ -260,7 +272,8 @@ function Date.fromSeconds(s)
 end
 
 --[=[
-@sm fromMilliseconds
+@m fromMilliseconds
+@t static
 @p ms number
 @r Date
 @d Constructs a new Date object from a Unix time in milliseconds.
@@ -270,7 +283,8 @@ function Date.fromMilliseconds(ms)
 end
 
 --[=[
-@sm fromMicroseconds
+@m fromMicroseconds
+@t static
 @p us number
 @r Date
 @d Constructs a new Date object from a Unix time in microseconds.

libs/utils/Deque.lua

@@ -1,5 +1,6 @@
 --[=[
-@ic Deque
+@c Deque
+@t ui
 @d An implementation of a double-ended queue.
 ]=]
 

libs/utils/Emitter.lua

@@ -1,5 +1,6 @@
 --[=[
-@ic Emitter
+@c Emitter
+@t ui
 @d Implements an asynchronous event emitter where callbacks can be subscribed to
 specific named events. When events are emitted, the callbacks are called in the
 order that they were originally registered.