Update docs

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 };
 

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 <typename T,
           typename std::enable_if<std::is_enum_v<T>, 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<T> to Lua and pushes it onto the stack.
+ *
+ * Needs StackIdx push(lua_State*, T); to work.
+ *
+ * @return Stack index of newly created table.
+ */
 template <typename T>
-int push(lua_State *L, std::vector<T> vec)
+StackIdx push(lua_State *L, std::vector<T> vec)
 {
     auto out = pushEmptyArray(L, vec.size());
     int i = 1;
@@ -78,8 +102,15 @@ int push(lua_State *L, std::vector<T> vec)
     return out;
 }
 
+/**
+ * @brief Converts a QList<T> to Lua and pushes it onto the stack.
+ *
+ * Needs StackIdx push(lua_State*, T); to work.
+ *
+ * @return Stack index of newly created table.
+ */
 template <typename T>
-int push(lua_State *L, QList<T> vec)
+StackIdx push(lua_State *L, QList<T> vec)
 {
     auto out = pushEmptyArray(L, vec.size());
     int i = 1;
@@ -92,6 +123,11 @@ int push(lua_State *L, QList<T> 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 <typename T, std::enable_if<std::is_enum_v<T>>>
 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 <typename T>
 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 <typename T>
 StackIdx pushEnumTable(lua_State *L)
 {

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<QString> listRegisteredCommands();
 
     const QDir &loadDirectory() const

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: