From c84fa5f15245718223ddea87d5cdf3a28422fbcd Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Tue, 15 Oct 2024 22:36:47 +0100 Subject: [PATCH] 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 --- .../utils/notify/notify.lua | 39 ++++++++++--------- .../utils/notify/validate.lua | 30 +++++++------- 2 files changed, 37 insertions(+), 32 deletions(-) diff --git a/worldeditadditions_core/utils/notify/notify.lua b/worldeditadditions_core/utils/notify/notify.lua index a53b6d9..994c652 100644 --- a/worldeditadditions_core/utils/notify/notify.lua +++ b/worldeditadditions_core/utils/notify/notify.lua @@ -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 : The name of the player to send the notification to. --- @param ntype : The type of notification. --- @param message : The message to send. --- @return : 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 : The name of the player to send the notification to. --- @param ntype : The type of notification. --- @param message : The message to send. --- @param colour (optional): The colour of the notification. --- @param message_coloured (optional): Whether the message should be coloured. --- @return : 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}, diff --git a/worldeditadditions_core/utils/notify/validate.lua b/worldeditadditions_core/utils/notify/validate.lua index 05a7e4b..dadba2a 100644 --- a/worldeditadditions_core/utils/notify/validate.lua +++ b/worldeditadditions_core/utils/notify/validate.lua @@ -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 : The name of the player to validate. --- - @returns : 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 : The message to validate. --- - @returns : 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 : The colour to validate. --- - @returns : 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 : The name of the player to validate. --- - @param message : The message to validate. --- - @param colour : The colour to validate. --- - @returns , : --- - : True if all parameters are valid, false otherwise. --- - : 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 = {