Adds method tags for documentation

.gitignore

@@ -0,0 +1 @@
+docs

docgen.lua

@@ -1,14 +1,15 @@
 --[=[
 @c ClassName [x base_1 x base_2 ... x base_n]
-@t tag (available: ui, abc)
+@t tag
+@mt methodTag (applies to all class methods)
 @p parameterName type
 @op optionalParameterName type
 @d description+
 ]=]
 
 --[=[
 @m methodName
-@t tag (available: static)
+@t tag
 @p parameterName type
 @op optionalParameterName type
 @r return
@@ -87,6 +88,10 @@ local function matchTags(s)
 	return gmatch(s, '@t (%S+)', true)
 end
 
+local function matchMethodTags(s)
+	return gmatch(s, '@mt (%S+)', true)
+end
+
 local function matchProperty(s)
 	local a, b, c = s:match('@p (%S+) (%S+) (.+)')
 	return {
@@ -132,6 +137,7 @@ local function newClass()
 		class.desc = matchDescription(s)
 		class.parameters = matchParameters(s)
 		class.tags = matchTags(s)
+		class.methodTags = matchMethodTags(s)
 		assert(not docs[class.name], 'duplicate class: ' .. class.name)
 		docs[class.name] = class
 	end
@@ -151,6 +157,10 @@ for f in coroutine.wrap(scan), './libs' do
 			initClass(s)
 		elseif t == 'm' then
 			local method = matchMethod(s)
+			for k, v in pairs(class.methodTags) do
+				method.tags[k] = v
+			end
+			method.class = class
 			insert(method.tags.static and class.statics or class.methods, method)
 		elseif t == 'p' then
 			insert(class.properties, matchProperty(s))
@@ -232,14 +242,53 @@ local function writeParameters(f, parameters)
 	end
 end
 
+local methodTags = {}
+
+methodTags['http'] = 'This method always makes an HTTP request.'
+methodTags['http?'] = 'This method may make an HTTP request.'
+methodTags['ws'] = 'This method always makes a WebSocket request.'
+methodTags['mem'] = 'This method only operates on data in memory.'
+methodTags['coro'] = 'This method creates and runs a new coroutine.'
+methodTags['coro?'] = 'This method may create and run a new coroutine.'
+
+local function checkTags(tbl, check)
+	for i, v in ipairs(check) do
+		if tbl[v] then
+			for j, w in ipairs(check) do
+				if i ~= j then
+					if tbl[w] then
+						return error(string.format('mutually exclusive tags encountered: %s and %s', v, w), 1)
+					end
+				end
+			end
+		end
+	end
+end
+
 local function writeMethods(f, methods)
+
 	sort(methods, sorter)
 	for _, method in ipairs(methods) do
+
 		f:write('### ', method.name)
 		writeParameters(f, method.parameters)
 		f:write(method.desc, '\n\n')
+
+		local tags = method.tags
+		checkTags(tags, {'http', 'http?', 'mem'})
+		checkTags(tags, {'ws', 'mem'})
+
+		for k in pairs(tags) do
+			if k ~= 'static' then
+				assert(methodTags[k], k)
+				f:write('*', methodTags[k], '*\n\n')
+			end
+		end
+
 		f:write('**Returns:** ', link(method.returnTypes), '\n\n----\n\n')
+
 	end
+
 end
 
 if not fs.existsSync(output) then
@@ -277,18 +326,17 @@ for _, class in pairs(docs) do
 
 	f:write(class.desc, '\n\n')
 
+	checkTags(class.tags, {'ui', 'abc'})
 	if class.tags.ui then
 		writeHeading(f, 'Constructor')
 		f:write('### ', class.name)
 		writeParameters(f, class.parameters)
+	elseif class.tags.abc then
+		f:write('*This is an abstract base class. Direct instances should never exist.*\n\n')
 	else
 		f:write('*Instances of this class should not be constructed by users.*\n\n')
 	end
 
-	if class.tags.abc then -- should be mutually exclusive with ui, but it's not enforced
-		f:write('*This is an abstract base class. Direct instances should never exist.*\n\n')
-	end
-
 	local properties = collectParents(parents, 'properties')
 	if next(properties) then
 		writeHeading(f, 'Properties Inherited From ' .. parentLinks)

libs/client/Client.lua

@@ -268,6 +268,7 @@ end
 
 --[=[
 @m run
+@t coro
 @p token string
 @op presence table
 @r nil
@@ -286,6 +287,7 @@ end
 
 --[=[
 @m stop
+@t ws
 @r nil
 @d Disconnects all shards and effectively stop their loops. This does not
 empty any data that the client may have cached.
@@ -309,6 +311,7 @@ end
 
 --[=[
 @m setUsername
+@t http
 @p username string
 @r boolean
 @d Sets the client's username. This must be between 2 and 32 characters in
@@ -320,6 +323,7 @@ end
 
 --[=[
 @m setAvatar
+@t http
 @p avatar Base64-Resolveable
 @r boolean
 @d Sets the client's avatar. To remove the avatar, pass an empty string or nil.
@@ -332,6 +336,7 @@ end
 
 --[=[
 @m createGuild
+@t http
 @p name string
 @r boolean
 @d Creates a new guild. The name must be between 2 and 100 characters in length.
@@ -350,6 +355,7 @@ end
 
 --[=[
 @m createGroupChannel
+@t http
 @r GroupChannel
 @d Creates a new group channel. This method is only available for user accounts.
 ]=]
@@ -364,6 +370,7 @@ end
 
 --[=[
 @m getWebhook
+@t http
 @p id string
 @r Webhook
 @d Gets a webhook object by ID. This always makes an HTTP request to obtain a
@@ -380,6 +387,7 @@ end
 
 --[=[
 @m getInvite
+@t http
 @p code string
 @op counts boolean
 @r Invite
@@ -397,6 +405,7 @@ end
 
 --[=[
 @m getUser
+@t http?
 @p id User-ID-Resolvable
 @r User
 @d Gets a user object by ID. If the object is already cached, then the cached
@@ -421,6 +430,7 @@ end
 
 --[=[
 @m getGuild
+@t mem
 @p id Guild-ID-Resolvable
 @r Guild
 @d Gets a guild object by ID. The current user must be in the guild and the client
@@ -434,6 +444,7 @@ end
 
 --[=[
 @m getChannel
+@t mem
 @p id Channel-ID-Resolvable
 @r Channel
 @d Gets a channel object by ID. For guild channels, the current user must be in
@@ -455,6 +466,7 @@ end
 
 --[=[
 @m getRole
+@t mem
 @p id Role-ID-Resolvable
 @r Role
 @d Gets a role object by ID. The current user must be in the role's guild and
@@ -468,6 +480,7 @@ end
 
 --[=[
 @m getEmoji
+@t mem
 @p id Emoji-ID-Resolvable
 @r Emoji
 @d Gets an emoji object by ID. The current user must be in the emoji's guild and
@@ -481,6 +494,7 @@ end
 
 --[=[
 @m listVoiceRegions
+@t http
 @r table
 @d Returns a raw data table that contains a list of voice regions as provided by
 Discord, with no formatting beyond what is provided by the Discord API.
@@ -491,6 +505,7 @@ end
 
 --[=[
 @m getConnections
+@t http
 @r table
 @d Returns a raw data table that contains a list of connections as provided by
 Discord, with no formatting beyond what is provided by the Discord API.
@@ -502,6 +517,7 @@ end
 
 --[=[
 @m getApplicationInformation
+@t http
 @r table
 @d Returns a raw data table that contains information about the current OAuth2
 application, with no formatting beyond what is provided by the Discord API.
@@ -523,6 +539,7 @@ end
 
 --[=[
 @m setStatus
+@t ws
 @p status string
 @r nil
 @d Sets the current users's status on all shards that are managed by this client.
@@ -545,6 +562,7 @@ end
 
 --[=[
 @m setGame
+@t ws
 @p game string/table
 @r nil
 @d Sets the current users's game on all shards that are managed by this client.
@@ -576,6 +594,7 @@ end
 
 --[=[
 @m setAFK
+@t ws
 @p afk boolean
 @r nil
 @d Set the current user's AFK status on all shards that are managed by this client.

libs/containers/AuditLogEntry.lua

@@ -29,6 +29,7 @@ end
 
 --[=[
 @m getBeforeAfter
+@t mem
 @r table
 @r table
 @d Returns two tables of the target's properties before the change, and after the change.
@@ -155,6 +156,7 @@ local targets = setmetatable({
 
 --[=[
 @m getTarget
+@t http?
 @r *
 @d Gets the target object of the affected entity. The returned object can be: [[Guild]],
 [[GuildChannel]], [[User]], [[Member]], [[Role]], [[Webhook]], [[Emoji]], nil
@@ -165,6 +167,7 @@ end
 
 --[=[
 @m getUser
+@t http?
 @r User
 @d Gets the user who performed the changes.
 ]=]
@@ -174,6 +177,7 @@ end
 
 --[=[
 @m getMember
+@t http?
 @r Member/nil
 @d Gets the member object of the user who performed the changes.
 ]=]

libs/containers/Ban.lua

@@ -24,6 +24,7 @@ end
 
 --[=[
 @m delete
+@t http
 @r boolean
 @d Deletes the ban object, unbanning the corresponding user.
 Equivalent to `Ban.guild:unbanUser(Ban.user)`.

libs/containers/Emoji.lua

@@ -47,6 +47,7 @@ end
 
 --[=[
 @m setName
+@t http
 @p name string
 @r boolean
 @d Sets the emoji's name. The name must be between 2 and 32 characters in length.
@@ -57,6 +58,7 @@ end
 
 --[=[
 @m setRoles
+@t http
 @p roles Role-ID-Resolvables
 @r boolean
 @d Sets the roles that can use the emoji.
@@ -68,6 +70,7 @@ end
 
 --[=[
 @m delete
+@t http
 @r boolean
 @d Permanently deletes the emoji. This cannot be undone!
 ]=]
@@ -86,6 +89,7 @@ end
 
 --[=[
 @m hasRole
+@t mem
 @p id Role-ID-Resolvable
 @r boolean
 @d Returns whether or not the provided role is allowed to use the emoji.

libs/containers/GroupChannel.lua

@@ -22,6 +22,7 @@ end
 
 --[=[
 @m setName
+@t http
 @p name string
 @r boolean
 @d Sets the channel's name. This must be between 1 and 100 characters in length.
@@ -32,6 +33,7 @@ end
 
 --[=[
 @m setIcon
+@t http
 @p icon Base64-Resolvable
 @r boolean
 @d Sets the channel's icon. To remove the icon, pass `nil`.
@@ -43,6 +45,7 @@ end
 
 --[=[
 @m addRecipient
+@t http
 @p id User-ID-Resolvable
 @r boolean
 @d Adds a user to the channel.
@@ -59,6 +62,7 @@ end
 
 --[=[
 @m removeRecipient
+@t http
 @p id User-ID-Resolvable
 @r boolean
 @d Removes a user from the channel.
@@ -75,6 +79,7 @@ end
 
 --[=[
 @m leave
+@t http
 @r boolean
 @d Removes the client's user from the channel. If no users remain, the channel
 is destroyed.