mirror of
https://github.com/sbrl/Minetest-WorldEditAdditions.git
synced 2024-11-22 15:33:00 +00:00
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:
parent
57d09a766b
commit
c84fa5f152
2 changed files with 37 additions and 32 deletions
|
@ -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},
|
||||
|
|
|
@ -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 = {
|
||||
|
|
Loading…
Reference in a new issue