Notify, Notify.validate: correct docblock comments so they work with moondoc

moondoc is the system we use for auto-generating Lua API docs

Ref https://github.com/sbrl/moondoc
This commit is contained in:
Starbeamrainbowlabs 2024-10-15 22:36:47 +01:00
parent 57d09a766b
commit c84fa5f152
Signed by: sbrl
GPG key ID: 1BE5172E637709C2
2 changed files with 37 additions and 32 deletions

View file

@ -16,8 +16,8 @@ local globalstate = {
local validate = dofile(wea_c.modpath .. "/utils/notify/validate.lua")
local split = dofile(wea_c.modpath .. "/utils/strings/split.lua")
-- @class worldeditadditions_core.notify
--- WorldEditAdditions player notification system.
-- @namespace worldeditadditions_core.notify
local Notify = {}
-- Local send handler
@ -57,10 +57,10 @@ end
--- Send a notification of type `ntype`.
-- (Same as `Notify[ntype](name, message)`)
-- @param name <string>: The name of the player to send the notification to.
-- @param ntype <string>: The type of notification.
-- @param message <string>: The message to send.
-- @return <table>: The Notify instance.
-- @param string name The name of the player to send the notification to.
-- @param string ntype The type of notification.
-- @param string message The message to send.
-- @return table The Notify instance.
function Notify.__call(name, ntype, message)
if ntype ~= "__call" and not Notify[ntype] then
Notify.error(name, "Invalid notification type: " .. ntype)
@ -72,25 +72,26 @@ function Notify.__call(name, ntype, message)
end
--- Send a custom notification.
-- @param name <string>: The name of the player to send the notification to.
-- @param ntype <string>: The type of notification.
-- @param message <string>: The message to send.
-- @param colour <string> (optional): The colour of the notification.
-- @param message_coloured <boolean> (optional): Whether the message should be coloured.
-- @return <boolean>: True if all parameters are valid, false otherwise.
function Notify.custom(name, ntype, message, colour, message_coloured)
if not colour then colour = "#FFFFFF" end
return send(name, ntype, message, colour, message_coloured)
end
--- Register predefined notification types.
-- @usage
-- @param string name The name of the player to send the notification to.
-- @param string ntype The type of notification.
-- @param string message The message to send.
-- @param string colour optional): The colour of the notification.
-- @param message_coloured boolean? Optional. Whether the message should be coloured.
-- @return boolean True if all parameters are valid, false otherwise.
-- @example Predefined notification types
-- Notify.error(name, message)
-- Notify.errinfo(name, message) -- For verbose errors and stack traces
-- Notify.warn(name, message)
-- Notify.wrninfo(name, message) -- For verbose warnings and stack traces
-- Notify.ok(name, message)
-- Notify.info(name, message)
function Notify.custom(name, ntype, message, colour, message_coloured)
if not colour then colour = "#FFFFFF" end
return send(name, ntype, message, colour, message_coloured)
end
--- Register the aforementioned predefined notification types.
do
local type_colours = {
error = {"#FF5555", true},

View file

@ -1,4 +1,6 @@
--- Validation functions for WorldEditAdditions notifications.
-- @internal
-- @namespace worldeditadditions_core.notify.validate
-- Helper functions
local log_error = function(message)
@ -6,12 +8,13 @@ local log_error = function(message)
" " .. debug.traceback())
end
--- Collection of functions to validate various parts of WorldEditAdditions notifications to ensure proper input for player names, messages, and colors.
-- @class validate
local validate = {}
--- Validate name
-- - @param name <string>: The name of the player to validate.
-- - @returns <boolean>: True if the name is valid, false otherwise.
-- @param string name The name of the player to validate.
-- @returns boolean True if the name is valid, false otherwise.
validate.name = function(name)
if type(name) ~= "string" then
log_error(tostring(name) .. " is a " .. type(name) .. " not a string.\n")
@ -27,13 +30,13 @@ validate.name = function(name)
end
--- Validate message
-- - @param message <string>: The message to validate.
-- - @returns <boolean>: True if the message is a string, false otherwise.
-- @param string message The message to validate.
-- @returns boolean True if the message is a string, false otherwise.
validate.message = function(message) return type(message) == "string" end
--- Validate colour
-- - @param colour <string>: The colour to validate.
-- - @returns <boolean>: True if the colour is valid, false otherwise.
-- @param string colour The colour to validate.
-- @returns boolean True if the colour is valid, false otherwise.
validate.colour = function(colour)
return ( type(colour) == "string" and
colour:match("^#%x+$") and
@ -41,13 +44,14 @@ validate.colour = function(colour)
end
--- Validate all
-- - @param name <string>: The name of the player to validate.
-- - @param message <string>: The message to validate.
-- - @param colour <string>: The colour to validate.
-- - @returns <boolean>, <table|nil>:
-- - <boolean>: True if all parameters are valid, false otherwise.
-- - <table|nil>: A table containing the fail state of the parameters
-- - or nil if player name is invalid.
-- @param string name The name of the player to validate.
-- @param string message The message to validate.
-- @param string colour The colour to validate.
-- @returns boolean, table|nil Returns the validation status, followed by details of the failure if bool == false.
-- | Return arg | Meaning |
-- |------------|---------|
-- | `boolean` | True if all parameters are valid, false otherwise. |
-- | `table|nil` | A table containing the fail state of the parameters or nil if player name is invalid. |
validate.all = function(name, message, colour)
local name_checked = validate.name(name)
local failed = {