From 6b476f28260edd3345835616843aa78c10ca94aa Mon Sep 17 00:00:00 2001 From: Mm2PL Date: Sat, 11 Feb 2023 12:57:16 +0100 Subject: [PATCH] Update docs --- src/controllers/plugins/LuaApi.hpp | 7 ++- src/controllers/plugins/LuaUtilities.hpp | 54 ++++++++++++++++++-- src/controllers/plugins/Plugin.hpp | 9 ++++ src/controllers/plugins/PluginController.hpp | 11 ++++ 4 files changed, 77 insertions(+), 4 deletions(-) diff --git a/src/controllers/plugins/LuaApi.hpp b/src/controllers/plugins/LuaApi.hpp index d058d6f47..859a6a67b 100644 --- a/src/controllers/plugins/LuaApi.hpp +++ b/src/controllers/plugins/LuaApi.hpp @@ -6,16 +6,21 @@ namespace chatterino::lua::api { // names in this namespace reflect what's visible inside Lua and follow the lua naming scheme // NOLINTBEGIN(readability-identifier-naming) +// Following functions are exposed in c2 table. int c2_register_command(lua_State *L); int c2_send_msg(lua_State *L); int c2_system_msg(lua_State *L); int c2_log(lua_State *L); +// These ones are global int g_load(lua_State *L); -int g_dofile(lua_State *L); int g_print(lua_State *L); + +// this one is exposed as execfile +int g_dofile(lua_State *L); // NOLINTEND(readability-identifier-naming) +// Exposed as c2.LogLevel // Represents "calls" to qCDebug, qCInfo ... enum LogLevel { Debug, Info, Warning, Critical }; diff --git a/src/controllers/plugins/LuaUtilities.hpp b/src/controllers/plugins/LuaUtilities.hpp index 99f9929b7..e0ce845d4 100644 --- a/src/controllers/plugins/LuaUtilities.hpp +++ b/src/controllers/plugins/LuaUtilities.hpp @@ -24,9 +24,21 @@ namespace chatterino::lua { */ QString humanErrorText(lua_State *L, int errCode); +/** + * Represents an index into Lua's stack + */ using StackIdx = int; +/** + * @brief Creates a table with countArray array properties on the Lua stack + * @return stack index of the newly created table + */ StackIdx pushEmptyArray(lua_State *L, int countArray); + +/** + * @brief Creates a table with countProperties named properties on the Lua stack + * @return stack index of the newly created table + */ StackIdx pushEmptyTable(lua_State *L, int countProperties); StackIdx push(lua_State *L, const CommandContext &ctx); @@ -40,11 +52,16 @@ bool peek(lua_State *L, QString *out, StackIdx idx = -1); bool peek(lua_State *L, QByteArray *out, StackIdx idx = -1); bool peek(lua_State *L, std::string *out, StackIdx idx = -1); -// forces conversion of value at idx to a string +/** + * @brief Converts Lua object at stack index idx to a string. + */ QString toString(lua_State *L, StackIdx idx = -1); /// TEMPLATES +/** + * @brief Converts object at stack index idx to enum given by template parameter T + */ template , bool>::type = true> bool peek(lua_State *L, T *out, StackIdx idx = -1) @@ -64,8 +81,15 @@ bool peek(lua_State *L, T *out, StackIdx idx = -1) return false; } +/** + * @brief Converts a vector to Lua and pushes it onto the stack. + * + * Needs StackIdx push(lua_State*, T); to work. + * + * @return Stack index of newly created table. + */ template -int push(lua_State *L, std::vector vec) +StackIdx push(lua_State *L, std::vector vec) { auto out = pushEmptyArray(L, vec.size()); int i = 1; @@ -78,8 +102,15 @@ int push(lua_State *L, std::vector vec) return out; } +/** + * @brief Converts a QList to Lua and pushes it onto the stack. + * + * Needs StackIdx push(lua_State*, T); to work. + * + * @return Stack index of newly created table. + */ template -int push(lua_State *L, QList vec) +StackIdx push(lua_State *L, QList vec) { auto out = pushEmptyArray(L, vec.size()); int i = 1; @@ -92,6 +123,11 @@ int push(lua_State *L, QList vec) return out; } +/** + * @brief Converts an enum given by T to Lua (into a string) and pushes it onto the stack. + * + * @return Stack index of newly created string. + */ template >> StackIdx push(lua_State *L, T inp) { @@ -99,6 +135,11 @@ StackIdx push(lua_State *L, T inp) return lua::push(L, std::string(name)); } +/** + * @brief Converts a Lua object into c++ and removes it from the stack. + * + * Relies on bool peek(lua_State*, T*, StackIdx) existing. + */ template bool pop(lua_State *L, T *out, StackIdx idx = -1) { @@ -110,6 +151,13 @@ bool pop(lua_State *L, T *out, StackIdx idx = -1) return ok; } +/** + * @brief Creates a table mapping enum names to unique values. + * + * Values in this table may change. + * + * @returns stack index of newly created table + */ template StackIdx pushEnumTable(lua_State *L) { diff --git a/src/controllers/plugins/Plugin.hpp b/src/controllers/plugins/Plugin.hpp index 7edc3f96b..5d67b2166 100644 --- a/src/controllers/plugins/Plugin.hpp +++ b/src/controllers/plugins/Plugin.hpp @@ -127,8 +127,17 @@ public: ~Plugin(); + /** + * @brief Perform all necessary tasks to bind a command name to this plugin + * @param name name of the command to create + * @param functionName name of the function that should be called when the command is executed + * @return true if addition succeeded, false otherwise (for example because the command name is already taken) + */ bool registerCommand(const QString &name, const QString &functionName); + /** + * @brief Get names of all commands belonging to this plugin + */ std::set listRegisteredCommands(); const QDir &loadDirectory() const diff --git a/src/controllers/plugins/PluginController.hpp b/src/controllers/plugins/PluginController.hpp index 51bc98918..5c491c8fc 100644 --- a/src/controllers/plugins/PluginController.hpp +++ b/src/controllers/plugins/PluginController.hpp @@ -51,7 +51,18 @@ public: return this->plugins_; } + /** + * @brief Reload plugin given by codename + * + * @param codename This is the 'codename' of the plugin, the name of the directory it is in + */ bool reload(const QString &codename); + + /** + * @brief Checks settings to tell if a plugin named by codename. + * + * It accounts for plugins being enabled/disabled globally. + */ static bool isEnabled(const QString &codename); private: