Merge pull request #3 from pessoa736/dev

feat: add help system, LuaDoc annotations, and improved AI documentation

Author: pessoa736

.github/copilot-instructions.md

@@ -47,3 +47,4 @@ luac.out
 /lua
 /lua_modules
 /.luarocks
+.pudimserver_initialized

.gitignore

@@ -24,10 +24,11 @@ local PortCheckParamsInter = utils:createInterface({
 local ServerChecks = {}
 ServerChecks.__index = ServerChecks
 
----@param Address string
----@param Port number|string
----@return boolean is_open
----@return string erro
+--- Checks if a TCP port is open on the given address.
+---@param Address string Host address to check
+---@param Port number|string Port number to check
+---@return boolean is_open True if the port is accepting connections
+---@return string message Description of the result
 function ServerChecks.is_Port_Open(Address, Port)
     local CIPO = log.inSection("Check: is Port Open")
 

PudimServer/ServerChecks.lua

@@ -33,8 +33,9 @@ local Cache = {}
 Cache.__index = Cache
 
 
----@param config? CacheConfig
----@return Cache
+--- Creates a new Cache instance with optional configuration.
+---@param config? CacheConfig Cache configuration (MaxSize, DefaultTTL)
+---@return Cache cache New cache instance
 function Cache.new(config)
   local CL = log.inSection("Cache")
 
@@ -50,8 +51,9 @@ function Cache.new(config)
 end
 
 
----@param key string
----@return string? response
+--- Retrieves a cached response by key. Returns nil if expired or not found.
+---@param key string Cache key (typically "METHOD:path")
+---@return string? response Cached HTTP response or nil
 function Cache:get(key)
   local entry = self._entries[key]
   if not entry then return nil end
@@ -66,9 +68,10 @@ function Cache:get(key)
 end
 
 
----@param key string
----@param response string
----@param ttl? number TTL em segundos (usa default se nil)
+--- Stores a response in the cache. Evicts oldest entry if cache is full.
+---@param key string Cache key (typically "METHOD:path")
+---@param response string HTTP response string to cache
+---@param ttl? number TTL in seconds (uses DefaultTTL if nil)
 function Cache:set(key, response, ttl)
   if not self._entries[key] then
     -- Evict oldest if full
@@ -85,7 +88,8 @@ function Cache:set(key, response, ttl)
 end
 
 
----@param key string
+--- Removes a single entry from the cache.
+---@param key string Cache key to invalidate
 function Cache:invalidate(key)
   if self._entries[key] then
     self._entries[key] = nil
@@ -94,6 +98,7 @@ function Cache:invalidate(key)
 end
 
 
+--- Removes all entries from the cache.
 function Cache:clear()
   self._entries = {}
   self._size = 0
@@ -118,9 +123,11 @@ function Cache:_evict()
 end
 
 
----@param cacheInstance Cache
----@param ttl? number TTL customizado
----@return PipelineEntry
+--- Creates a PipelineEntry that caches GET responses.
+--- Only caches GET requests. Cache key format: "method:path".
+---@param cacheInstance Cache The cache instance to use
+---@param ttl? number Custom TTL in seconds (uses cache's DefaultTTL if nil)
+---@return PipelineEntry entry Pipeline handler ready for Server:UseHandler()
 function Cache.createPipelineHandler(cacheInstance, ttl)
   return {
     name = "cache",

PudimServer/cache.lua

@@ -46,6 +46,9 @@ end
 ---@param config? CorsConfig
 ---@return table corsHeaders Headers CORS resolvidos
 ---@return CorsConfig resolvedConfig Config com defaults aplicados
+--- Creates a resolved CORS configuration with defaults applied.
+---@param config? CorsConfig Raw CORS configuration
+---@return table resolvedConfig Config with all defaults filled in
 function cors.createConfig(config)
   local CL = log.inSection("CORS")
 
@@ -65,9 +68,10 @@ function cors.createConfig(config)
 end
 
 
----@param config table Config resolvida do CORS
----@param requestOrigin string? Origin do request
----@return table headers Headers CORS para adicionar na resposta
+--- Builds CORS response headers from a resolved config.
+---@param config table Resolved CORS config (from createConfig)
+---@param requestOrigin? string Origin header from the request
+---@return table<string, string> headers CORS headers to add to the response
 function cors.buildHeaders(config, requestOrigin)
   local headers = {}
 
@@ -89,8 +93,9 @@ function cors.buildHeaders(config, requestOrigin)
 end
 
 
----@param config table Config resolvida do CORS
----@return string Resposta HTTP para preflight
+--- Returns a 204 No Content HTTP response for CORS preflight (OPTIONS) requests.
+---@param config table Resolved CORS config (from createConfig)
+---@return string response HTTP response string for preflight
 function cors.preflightResponse(config)
   local http = require("PudimServer.http")
   local headers = cors.buildHeaders(config)