From e9d3fb21f038c692160bceb2ff5bd3d16529f76b Mon Sep 17 00:00:00 2001 From: Filip Tibell Date: Thu, 26 Jan 2023 19:56:50 -0500 Subject: [PATCH] Add missing param and return docs to definitions --- luneDocs.json | 284 ++++++++++++++++++++++++++++++++++++----- luneTypes.d.luau | 52 ++++++++ src/cli/gen/visitor.rs | 2 +- 3 files changed, 308 insertions(+), 30 deletions(-) diff --git a/luneDocs.json b/luneDocs.json index 0d731fd..ba44d9e 100644 --- a/luneDocs.json +++ b/luneDocs.json @@ -11,30 +11,67 @@ "code_sample": "", "documentation": "Prints arguments as a human-readable string with syntax highlighting for tables to stderr.\n\nThis will also prepend an [ERROR] tag at the beginning of the message.\n\nUsing this function will automatically set the exit code of the process\nto 1, unless it gets manually specified afterwards using `process.exit`.", "learn_more_link": "", - "params": [], + "params": [ + { + "documentation": "@roblox/global/console.error/param/0", + "name": "..." + } + ], "returns": [] }, + "@roblox/global/console.error/param/0": { + "documentation": "The values to print out to stderr" + }, "@roblox/global/console.format": { "code_sample": "", "documentation": "Formats arguments into a human-readable string with syntax highlighting for tables.", "learn_more_link": "", - "params": [], - "returns": [] + "params": [ + { + "documentation": "@roblox/global/console.format/param/0", + "name": "..." + } + ], + "returns": [ + "@roblox/global/console.format/return/0" + ] + }, + "@roblox/global/console.format/param/0": { + "documentation": "The values to format" + }, + "@roblox/global/console.format/return/0": { + "documentation": "The formatted string" }, "@roblox/global/console.info": { "code_sample": "", "documentation": "Prints arguments as a human-readable string with syntax highlighting for tables to stdout.\n\nThis will also prepend an [INFO] tag at the beginning of the message.", "learn_more_link": "", - "params": [], + "params": [ + { + "documentation": "@roblox/global/console.info/param/0", + "name": "..." + } + ], "returns": [] }, + "@roblox/global/console.info/param/0": { + "documentation": "The values to print out" + }, "@roblox/global/console.log": { "code_sample": "", "documentation": "Prints arguments as a human-readable string with syntax highlighting for tables to stdout.", "learn_more_link": "", - "params": [], + "params": [ + { + "documentation": "@roblox/global/console.log/param/0", + "name": "..." + } + ], "returns": [] }, + "@roblox/global/console.log/param/0": { + "documentation": "The values to print out" + }, "@roblox/global/console.resetColor": { "code_sample": "", "documentation": "Resets the current persistent output color.", @@ -53,23 +90,47 @@ "code_sample": "", "documentation": "Sets the current persistent output color.", "learn_more_link": "", - "params": [], + "params": [ + { + "documentation": "@roblox/global/console.setColor/param/0", + "name": "color" + } + ], "returns": [] }, + "@roblox/global/console.setColor/param/0": { + "documentation": "The color to set" + }, "@roblox/global/console.setStyle": { "code_sample": "", "documentation": "Sets the current persistent output style.", "learn_more_link": "", - "params": [], + "params": [ + { + "documentation": "@roblox/global/console.setStyle/param/0", + "name": "style" + } + ], "returns": [] }, + "@roblox/global/console.setStyle/param/0": { + "documentation": "The style to set" + }, "@roblox/global/console.warn": { "code_sample": "", "documentation": "Prints arguments as a human-readable string with syntax highlighting for tables to stdout.\n\nThis will also prepend an [INFO] tag at the beginning of the message.", "learn_more_link": "", - "params": [], + "params": [ + { + "documentation": "@roblox/global/console.warn/param/0", + "name": "..." + } + ], "returns": [] }, + "@roblox/global/console.warn/param/0": { + "documentation": "The values to print out" + }, "@roblox/global/fs": { "code_sample": "", "documentation": "Filesystem", @@ -82,58 +143,149 @@ "code_sample": "", "documentation": "Checks if a given path is a directory.\n\nAn error will be thrown in the following situations:\n\n* The current process lacks permissions to read at `path`.\n* Some other I/O error occurred.", "learn_more_link": "", - "params": [], - "returns": [] + "params": [ + { + "documentation": "@roblox/global/fs.isDir/param/0", + "name": "path" + } + ], + "returns": [ + "@roblox/global/fs.isDir/return/0" + ] + }, + "@roblox/global/fs.isDir/param/0": { + "documentation": "The directory path to check" + }, + "@roblox/global/fs.isDir/return/0": { + "documentation": "If the path is a directory or not" }, "@roblox/global/fs.isFile": { "code_sample": "", "documentation": "Checks if a given path is a file.\n\nAn error will be thrown in the following situations:\n\n* The current process lacks permissions to read at `path`.\n* Some other I/O error occurred.", "learn_more_link": "", - "params": [], - "returns": [] + "params": [ + { + "documentation": "@roblox/global/fs.isFile/param/0", + "name": "path" + } + ], + "returns": [ + "@roblox/global/fs.isFile/return/0" + ] + }, + "@roblox/global/fs.isFile/param/0": { + "documentation": "The file path to check" + }, + "@roblox/global/fs.isFile/return/0": { + "documentation": "If the path is a file or not" }, "@roblox/global/fs.readDir": { "code_sample": "", "documentation": "Reads entries in a directory at `path`.\n\nAn error will be thrown in the following situations:\n\n* `path` does not point to an existing directory.\n* The current process lacks permissions to read the contents of the directory.\n* Some other I/O error occurred.", "learn_more_link": "", - "params": [], - "returns": [] + "params": [ + { + "documentation": "@roblox/global/fs.readDir/param/0", + "name": "path" + } + ], + "returns": [ + "@roblox/global/fs.readDir/return/0" + ] + }, + "@roblox/global/fs.readDir/param/0": { + "documentation": "The directory path to search in" + }, + "@roblox/global/fs.readDir/return/0": { + "documentation": "A list of files & directories found" }, "@roblox/global/fs.readFile": { "code_sample": "", "documentation": "Reads a file at `path`.\n\nAn error will be thrown in the following situations:\n\n* `path` does not point to an existing file.\n* The current process lacks permissions to read the file.\n* The contents of the file cannot be read as a UTF-8 string.\n* Some other I/O error occurred.", "learn_more_link": "", - "params": [], - "returns": [] + "params": [ + { + "documentation": "@roblox/global/fs.readFile/param/0", + "name": "path" + } + ], + "returns": [ + "@roblox/global/fs.readFile/return/0" + ] + }, + "@roblox/global/fs.readFile/param/0": { + "documentation": "The path to the file to read" + }, + "@roblox/global/fs.readFile/return/0": { + "documentation": "The contents of the file" }, "@roblox/global/fs.removeDir": { "code_sample": "", "documentation": "Removes a directory and all of its contents.\n\nAn error will be thrown in the following situations:\n\n* `path` is not an existing and empty directory.\n* The current process lacks permissions to remove the directory.\n* Some other I/O error occurred.", "learn_more_link": "", - "params": [], + "params": [ + { + "documentation": "@roblox/global/fs.removeDir/param/0", + "name": "path" + } + ], "returns": [] }, + "@roblox/global/fs.removeDir/param/0": { + "documentation": "The directory to remove" + }, "@roblox/global/fs.removeFile": { "code_sample": "", "documentation": "Removes a file.\n\nAn error will be thrown in the following situations:\n\n* `path` does not point to an existing file.\n* The current process lacks permissions to remove the file.\n* Some other I/O error occurred.", "learn_more_link": "", - "params": [], + "params": [ + { + "documentation": "@roblox/global/fs.removeFile/param/0", + "name": "path" + } + ], "returns": [] }, + "@roblox/global/fs.removeFile/param/0": { + "documentation": "The file to remove" + }, "@roblox/global/fs.writeDir": { "code_sample": "", "documentation": "Creates a directory and its parent directories if they are missing.\n\nAn error will be thrown in the following situations:\n\n* `path` already points to an existing file or directory.\n* The current process lacks permissions to create the directory or its missing parents.\n* Some other I/O error occurred.", "learn_more_link": "", - "params": [], + "params": [ + { + "documentation": "@roblox/global/fs.writeDir/param/0", + "name": "path" + } + ], "returns": [] }, + "@roblox/global/fs.writeDir/param/0": { + "documentation": "The directory to create" + }, "@roblox/global/fs.writeFile": { "code_sample": "", "documentation": "Writes to a file at `path`.\n\nAn error will be thrown in the following situations:\n\n* The file's parent directory does not exist.\n* The current process lacks permissions to write to the file.\n* Some other I/O error occurred.", "learn_more_link": "", - "params": [], + "params": [ + { + "documentation": "@roblox/global/fs.writeFile/param/0", + "name": "path" + }, + { + "documentation": "@roblox/global/fs.writeFile/param/1", + "name": "contents" + } + ], "returns": [] }, + "@roblox/global/fs.writeFile/param/0": { + "documentation": "The path of the file" + }, + "@roblox/global/fs.writeFile/param/1": { + "documentation": "The contents of the file" + }, "@roblox/global/net": { "code_sample": "", "documentation": "Networking", @@ -146,22 +298,68 @@ "code_sample": "", "documentation": "Decodes the given JSON string into a lua value.", "learn_more_link": "", - "params": [], - "returns": [] + "params": [ + { + "documentation": "@roblox/global/net.jsonDecode/param/0", + "name": "encoded" + } + ], + "returns": [ + "@roblox/global/net.jsonDecode/return/0" + ] + }, + "@roblox/global/net.jsonDecode/param/0": { + "documentation": "The JSON string to decode" + }, + "@roblox/global/net.jsonDecode/return/0": { + "documentation": "The decoded lua value" }, "@roblox/global/net.jsonEncode": { "code_sample": "", "documentation": "Encodes the given value as JSON.", "learn_more_link": "", - "params": [], - "returns": [] + "params": [ + { + "documentation": "@roblox/global/net.jsonEncode/param/0", + "name": "value" + }, + { + "documentation": "@roblox/global/net.jsonEncode/param/1", + "name": "pretty" + } + ], + "returns": [ + "@roblox/global/net.jsonEncode/return/0" + ] + }, + "@roblox/global/net.jsonEncode/param/0": { + "documentation": "The value to encode as JSON" + }, + "@roblox/global/net.jsonEncode/param/1": { + "documentation": "If the encoded JSON string should include newlines and spaces. Defaults to false" + }, + "@roblox/global/net.jsonEncode/return/0": { + "documentation": "The encoded JSON string" }, "@roblox/global/net.request": { "code_sample": "", "documentation": "Sends an HTTP request using the given url and / or parameters, and returns a dictionary that describes the response received.\n\nOnly throws an error if a miscellaneous network or I/O error occurs, never for unsuccessful status codes.", "learn_more_link": "", - "params": [], - "returns": [] + "params": [ + { + "documentation": "@roblox/global/net.request/param/0", + "name": "config" + } + ], + "returns": [ + "@roblox/global/net.request/return/0" + ] + }, + "@roblox/global/net.request/param/0": { + "documentation": "The URL or request config to use" + }, + "@roblox/global/net.request/return/0": { + "documentation": "A dictionary representing the response for the request" }, "@roblox/global/process": { "code_sample": "", @@ -189,15 +387,43 @@ "code_sample": "", "documentation": "Exits the currently running script as soon as possible with the given exit code.\n\nExit code 0 is treated as a successful exit, any other value is treated as an error.\n\nSetting the exit code using this function will override any otherwise automatic exit code.", "learn_more_link": "", - "params": [], + "params": [ + { + "documentation": "@roblox/global/process.exit/param/0", + "name": "code" + } + ], "returns": [] }, + "@roblox/global/process.exit/param/0": { + "documentation": "The exit code to set" + }, "@roblox/global/process.spawn": { "code_sample": "", "documentation": "Spawns a child process that will run the program `program` with the given `params` as arguments, and returns a dictionary that describes the final status and ouput of the child process.", "learn_more_link": "", - "params": [], - "returns": [] + "params": [ + { + "documentation": "@roblox/global/process.spawn/param/0", + "name": "program" + }, + { + "documentation": "@roblox/global/process.spawn/param/1", + "name": "params" + } + ], + "returns": [ + "@roblox/global/process.spawn/return/0" + ] + }, + "@roblox/global/process.spawn/param/0": { + "documentation": "The program to spawn as a child process" + }, + "@roblox/global/process.spawn/param/1": { + "documentation": "Additional parameters to pass to the program" + }, + "@roblox/global/process.spawn/return/0": { + "documentation": "A dictionary representing the result of the child process" }, "@roblox/global/task": { "code_sample": "", diff --git a/luneTypes.d.luau b/luneTypes.d.luau index a5b3ad3..002b072 100644 --- a/luneTypes.d.luau +++ b/luneTypes.d.luau @@ -16,6 +16,8 @@ declare console: { @within console Sets the current persistent output color. + + @param color The color to set ]=] setColor: (color: "black" | "red" | "green" | "yellow" | "blue" | "purple" | "cyan" | "white") -> (), --[=[ @@ -28,18 +30,25 @@ declare console: { @within console Sets the current persistent output style. + + @param style The style to set ]=] setStyle: (style: "bold" | "dim") -> (), --[=[ @within console Formats arguments into a human-readable string with syntax highlighting for tables. + + @param ... The values to format + @return The formatted string ]=] format: (...any) -> (string), --[=[ @within console Prints arguments as a human-readable string with syntax highlighting for tables to stdout. + + @param ... The values to print out ]=] log: (...any) -> (), --[=[ @@ -48,6 +57,8 @@ declare console: { Prints arguments as a human-readable string with syntax highlighting for tables to stdout. This will also prepend an [INFO] tag at the beginning of the message. + + @param ... The values to print out ]=] info: (...any) -> (), --[=[ @@ -56,6 +67,8 @@ declare console: { Prints arguments as a human-readable string with syntax highlighting for tables to stdout. This will also prepend an [INFO] tag at the beginning of the message. + + @param ... The values to print out ]=] warn: (...any) -> (), --[=[ @@ -67,6 +80,8 @@ declare console: { Using this function will automatically set the exit code of the process to 1, unless it gets manually specified afterwards using `process.exit`. + + @param ... The values to print out to stderr ]=] error: (...any) -> (), } @@ -88,6 +103,9 @@ declare fs: { * The current process lacks permissions to read the file. * The contents of the file cannot be read as a UTF-8 string. * Some other I/O error occurred. + + @param path The path to the file to read + @return The contents of the file ]=] readFile: (path: string) -> string, --[=[ @@ -100,6 +118,9 @@ declare fs: { * `path` does not point to an existing directory. * The current process lacks permissions to read the contents of the directory. * Some other I/O error occurred. + + @param path The directory path to search in + @return A list of files & directories found ]=] readDir: (path: string) -> { string }, --[=[ @@ -112,6 +133,9 @@ declare fs: { * The file's parent directory does not exist. * The current process lacks permissions to write to the file. * Some other I/O error occurred. + + @param path The path of the file + @param contents The contents of the file ]=] writeFile: (path: string, contents: string) -> (), --[=[ @@ -124,6 +148,8 @@ declare fs: { * `path` already points to an existing file or directory. * The current process lacks permissions to create the directory or its missing parents. * Some other I/O error occurred. + + @param path The directory to create ]=] writeDir: (path: string) -> (), --[=[ @@ -136,6 +162,8 @@ declare fs: { * `path` does not point to an existing file. * The current process lacks permissions to remove the file. * Some other I/O error occurred. + + @param path The file to remove ]=] removeFile: (path: string) -> (), --[=[ @@ -148,6 +176,8 @@ declare fs: { * `path` is not an existing and empty directory. * The current process lacks permissions to remove the directory. * Some other I/O error occurred. + + @param path The directory to remove ]=] removeDir: (path: string) -> (), --[=[ @@ -159,6 +189,9 @@ declare fs: { * The current process lacks permissions to read at `path`. * Some other I/O error occurred. + + @param path The file path to check + @return If the path is a file or not ]=] isFile: (path: string) -> boolean, --[=[ @@ -170,6 +203,9 @@ declare fs: { * The current process lacks permissions to read at `path`. * Some other I/O error occurred. + + @param path The directory path to check + @return If the path is a directory or not ]=] isDir: (path: string) -> boolean, } @@ -186,6 +222,9 @@ declare net: { Sends an HTTP request using the given url and / or parameters, and returns a dictionary that describes the response received. Only throws an error if a miscellaneous network or I/O error occurs, never for unsuccessful status codes. + + @param config The URL or request config to use + @return A dictionary representing the response for the request ]=] request: (config: string | { url: string, @@ -203,12 +242,19 @@ declare net: { @within net Encodes the given value as JSON. + + @param value The value to encode as JSON + @param pretty If the encoded JSON string should include newlines and spaces. Defaults to false + @return The encoded JSON string ]=] jsonEncode: (value: any, pretty: boolean?) -> string, --[=[ @within net Decodes the given JSON string into a lua value. + + @param encoded The JSON string to decode + @return The decoded lua value ]=] jsonDecode: (encoded: string) -> any, } @@ -241,12 +287,18 @@ declare process: { Exit code 0 is treated as a successful exit, any other value is treated as an error. Setting the exit code using this function will override any otherwise automatic exit code. + + @param code The exit code to set ]=] exit: (code: number?) -> (), --[=[ @within process Spawns a child process that will run the program `program` with the given `params` as arguments, and returns a dictionary that describes the final status and ouput of the child process. + + @param program The program to spawn as a child process + @param params Additional parameters to pass to the program + @return A dictionary representing the result of the child process ]=] spawn: (program: string, params: { string }?) -> { ok: boolean, diff --git a/src/cli/gen/visitor.rs b/src/cli/gen/visitor.rs index 44d4389..ac211ee 100644 --- a/src/cli/gen/visitor.rs +++ b/src/cli/gen/visitor.rs @@ -20,7 +20,7 @@ pub struct DocumentationVisitor { impl DocumentationVisitor { pub fn new() -> Self { - let tag_regex = Regex::new(r#"^@(\w+)\s+(\w+)(.*)$"#).unwrap(); + let tag_regex = Regex::new(r#"^@(\S+)\s+(\S+)(.*)$"#).unwrap(); Self { globals: vec![], functions: vec![],