fix(luals-meta): Use opaque enum values and correct HTTP types (#5682)

CHANGELOG.md

@@ -75,7 +75,7 @@
 - Dev: Removed unused timegate settings. (#5361)
 - Dev: Add `Channel::addSystemMessage` helper function, allowing us to avoid the common `channel->addMessage(makeSystemMessage(...));` pattern. (#5500)
 - Dev: Unsingletonize `Resources2`. (#5460)
-- Dev: All Lua globals now show in the `c2` global in the LuaLS metadata. (#5385)
+- Dev: All Lua globals now show in the `c2` global in the LuaLS metadata. (#5385, #5682)
 - Dev: Images are now loaded in worker threads. (#5431)
 - Dev: Fixed broken `SignalVector::operator[]` implementation. (#5556)
 - Dev: Qt Creator now auto-configures Conan when loading the project and skips vcpkg. (#5305)
@@ -110,7 +110,7 @@
 - Dev: Twitch messages are now sent using Twitch's Helix API instead of IRC by default. (#5607)
 - Dev: `GIFTimer` is no longer initialized in tests. (#5608)
 - Dev: Emojis now use flags instead of a set of strings for capabilities. (#5616)
-- Dev: Move plugins to Sol2. (#5622)
+- Dev: Move plugins to Sol2. (#5622, #5682)
 - Dev: Refactored static `MessageBuilder` helpers to standalone functions. (#5652)
 - Dev: Decoupled reply parsing from `MessageBuilder`. (#5660, #5668)
 - Dev: Refactored IRC message building. (#5663)

docs/plugin-meta.lua

@@ -5,20 +5,20 @@
 -- Add the folder this file is in to "Lua.workspace.library".
 
 c2 = {}
----@alias c2.LogLevel.Debug "c2.LogLevel.Debug"
+---@enum c2.LogLevel
----@alias c2.LogLevel.Info "c2.LogLevel.Info"
+c2.LogLevel = {
----@alias c2.LogLevel.Warning "c2.LogLevel.Warning"
+    Debug = {}, ---@type c2.LogLevel.Debug
----@alias c2.LogLevel.Critical "c2.LogLevel.Critical"
+    Info = {}, ---@type c2.LogLevel.Info
----@alias c2.LogLevel c2.LogLevel.Debug|c2.LogLevel.Info|c2.LogLevel.Warning|c2.LogLevel.Critical
+    Warning = {}, ---@type c2.LogLevel.Warning
----@type { Debug: c2.LogLevel.Debug, Info: c2.LogLevel.Info, Warning: c2.LogLevel.Warning, Critical: c2.LogLevel.Critical }
+    Critical = {}, ---@type c2.LogLevel.Critical
-c2.LogLevel = {}
+}
 
 -- Begin src/controllers/plugins/api/EventType.hpp
 
----@alias c2.EventType.CompletionRequested "c2.EventType.CompletionRequested"
+---@enum c2.EventType
----@alias c2.EventType c2.EventType.CompletionRequested
+c2.EventType = {
----@type { CompletionRequested: c2.EventType.CompletionRequested }
+    CompletionRequested = {}, ---@type c2.EventType.CompletionRequested
-c2.EventType = {}
+}
 
 -- End src/controllers/plugins/api/EventType.hpp
 
@@ -38,19 +38,19 @@ c2.EventType = {}
 
 -- Begin src/common/Channel.hpp
 
----@alias c2.ChannelType.None "c2.ChannelType.None"
+---@enum c2.ChannelType
----@alias c2.ChannelType.Direct "c2.ChannelType.Direct"
+c2.ChannelType = {
----@alias c2.ChannelType.Twitch "c2.ChannelType.Twitch"
+    None = {}, ---@type c2.ChannelType.None
----@alias c2.ChannelType.TwitchWhispers "c2.ChannelType.TwitchWhispers"
+    Direct = {}, ---@type c2.ChannelType.Direct
----@alias c2.ChannelType.TwitchWatching "c2.ChannelType.TwitchWatching"
+    Twitch = {}, ---@type c2.ChannelType.Twitch
----@alias c2.ChannelType.TwitchMentions "c2.ChannelType.TwitchMentions"
+    TwitchWhispers = {}, ---@type c2.ChannelType.TwitchWhispers
----@alias c2.ChannelType.TwitchLive "c2.ChannelType.TwitchLive"
+    TwitchWatching = {}, ---@type c2.ChannelType.TwitchWatching
----@alias c2.ChannelType.TwitchAutomod "c2.ChannelType.TwitchAutomod"
+    TwitchMentions = {}, ---@type c2.ChannelType.TwitchMentions
----@alias c2.ChannelType.TwitchEnd "c2.ChannelType.TwitchEnd"
+    TwitchLive = {}, ---@type c2.ChannelType.TwitchLive
----@alias c2.ChannelType.Misc "c2.ChannelType.Misc"
+    TwitchAutomod = {}, ---@type c2.ChannelType.TwitchAutomod
----@alias c2.ChannelType c2.ChannelType.None|c2.ChannelType.Direct|c2.ChannelType.Twitch|c2.ChannelType.TwitchWhispers|c2.ChannelType.TwitchWatching|c2.ChannelType.TwitchMentions|c2.ChannelType.TwitchLive|c2.ChannelType.TwitchAutomod|c2.ChannelType.TwitchEnd|c2.ChannelType.Misc
+    TwitchEnd = {}, ---@type c2.ChannelType.TwitchEnd
----@type { None: c2.ChannelType.None, Direct: c2.ChannelType.Direct, Twitch: c2.ChannelType.Twitch, TwitchWhispers: c2.ChannelType.TwitchWhispers, TwitchWatching: c2.ChannelType.TwitchWatching, TwitchMentions: c2.ChannelType.TwitchMentions, TwitchLive: c2.ChannelType.TwitchLive, TwitchAutomod: c2.ChannelType.TwitchAutomod, TwitchEnd: c2.ChannelType.TwitchEnd, Misc: c2.ChannelType.Misc }
+    Misc = {}, ---@type c2.ChannelType.Misc
-c2.ChannelType = {}
+}
 
 -- End src/common/Channel.hpp
 
@@ -174,90 +174,97 @@ function c2.Channel.by_twitch_id(id) end
 
 -- Begin src/controllers/plugins/api/HTTPResponse.hpp
 
----@class HTTPResponse
+---@class c2.HTTPResponse
-HTTPResponse = {}
+c2.HTTPResponse = {}
 
 --- Returns the data. This is not guaranteed to be encoded using any
 --- particular encoding scheme. It's just the bytes the server returned.
 ---
-function HTTPResponse:data() end
+---@return string
+---@nodiscard
+function c2.HTTPResponse:data() end
 
 --- Returns the status code.
 ---
-function HTTPResponse:status() end
+---@return number|nil
+---@nodiscard
+function c2.HTTPResponse:status() end
 
 --- A somewhat human readable description of an error if such happened
 ---
-function HTTPResponse:error() end
+---@return string
+---@nodiscard
+function c2.HTTPResponse:error() end
 
 ---@return string
-function HTTPResponse:__tostring() end
+---@nodiscard
+function c2.HTTPResponse:__tostring() end
 
 -- End src/controllers/plugins/api/HTTPResponse.hpp
 
 -- Begin src/controllers/plugins/api/HTTPRequest.hpp
 
----@alias HTTPCallback fun(result: HTTPResponse): nil
+---@alias c2.HTTPCallback fun(result: c2.HTTPResponse): nil
----@class HTTPRequest
+---@class c2.HTTPRequest
-HTTPRequest = {}
+c2.HTTPRequest = {}
 
 --- Sets the success callback
 ---
----@param callback HTTPCallback Function to call when the HTTP request succeeds
+---@param callback c2.HTTPCallback Function to call when the HTTP request succeeds
-function HTTPRequest:on_success(callback) end
+function c2.HTTPRequest:on_success(callback) end
 
 --- Sets the failure callback
 ---
----@param callback HTTPCallback Function to call when the HTTP request fails or returns a non-ok status
+---@param callback c2.HTTPCallback Function to call when the HTTP request fails or returns a non-ok status
-function HTTPRequest:on_error(callback) end
+function c2.HTTPRequest:on_error(callback) end
 
 --- Sets the finally callback
 ---
 ---@param callback fun(): nil Function to call when the HTTP request finishes
-function HTTPRequest:finally(callback) end
+function c2.HTTPRequest:finally(callback) end
 
 --- Sets the timeout
 ---
 ---@param timeout integer How long in milliseconds until the times out
-function HTTPRequest:set_timeout(timeout) end
+function c2.HTTPRequest:set_timeout(timeout) end
 
 --- Sets the request payload
 ---
 ---@param data string
-function HTTPRequest:set_payload(data) end
+function c2.HTTPRequest:set_payload(data) end
 
 --- Sets a header in the request
 ---
 ---@param name string
 ---@param value string
-function HTTPRequest:set_header(name, value) end
+function c2.HTTPRequest:set_header(name, value) end
 
 --- Executes the HTTP request
 ---
-function HTTPRequest:execute() end
+function c2.HTTPRequest:execute() end
 
 ---@return string
-function HTTPRequest:__tostring() end
+function c2.HTTPRequest:__tostring() end
 
 --- Creates a new HTTPRequest
 ---
----@param method HTTPMethod Method to use
+---@param method c2.HTTPMethod Method to use
 ---@param url string Where to send the request to
----@return HTTPRequest
+---@return c2.HTTPRequest
-function HTTPRequest.create(method, url) end
+function c2.HTTPRequest.create(method, url) end
 
 -- End src/controllers/plugins/api/HTTPRequest.hpp
 
 -- Begin src/common/network/NetworkCommon.hpp
 
----@alias HTTPMethod.Get "HTTPMethod.Get"
+---@enum c2.HTTPMethod
----@alias HTTPMethod.Post "HTTPMethod.Post"
+c2.HTTPMethod = {
----@alias HTTPMethod.Put "HTTPMethod.Put"
+    Get = {}, ---@type c2.HTTPMethod.Get
----@alias HTTPMethod.Delete "HTTPMethod.Delete"
+    Post = {}, ---@type c2.HTTPMethod.Post
----@alias HTTPMethod.Patch "HTTPMethod.Patch"
+    Put = {}, ---@type c2.HTTPMethod.Put
----@alias HTTPMethod HTTPMethod.Get|HTTPMethod.Post|HTTPMethod.Put|HTTPMethod.Delete|HTTPMethod.Patch
+    Delete = {}, ---@type c2.HTTPMethod.Delete
----@type { Get: HTTPMethod.Get, Post: HTTPMethod.Post, Put: HTTPMethod.Put, Delete: HTTPMethod.Delete, Patch: HTTPMethod.Patch }
+    Patch = {}, ---@type c2.HTTPMethod.Patch
-HTTPMethod = {}
+}
 
 -- End src/common/network/NetworkCommon.hpp
 

scripts/make_luals_meta.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 """
 This script generates docs/plugin-meta.lua. It accepts no arguments
 
@@ -242,25 +243,19 @@ def read_file(path: Path, out: TextIOWrapper):
                 )
             name = header[0].split(" ", 1)[1]
             printmsg(path, reader.line_no(), f"enum {name}")
-            variants = reader.read_enum_variants()
-
-            vtypes = []
-            for variant in variants:
-                vtype = f'{name}.{variant}'
-                vtypes.append(vtype)
-                out.write(f'---@alias {vtype} "{vtype}"\n')
-
-            out.write(f"---@alias {name} {'|'.join(vtypes)}\n")
             if header_comment:
                 out.write(f"--- {header_comment}\n")
-            out.write("---@type { ")
+            out.write(f"---@enum {name}\n")
+            out.write(f"{name} = {{\n")
             out.write(
-                ", ".join(
+                "\n".join(
-                    [f"{variant}: {typ}" for variant, typ in zip(variants,vtypes)]
+                    [
+                        f"    {variant} = {{}}, ---@type {name}.{variant}"
+                        for variant in reader.read_enum_variants()
+                    ]
                 )
             )
-            out.write(" }\n")
+            out.write("\n}\n\n")
-            out.write(f"{name} = {{}}\n\n")
             continue
 
         # class

src/common/network/NetworkCommon.hpp

@@ -16,7 +16,7 @@ using NetworkErrorCallback = std::function<void(NetworkResult)>;
 using NetworkFinallyCallback = std::function<void()>;
 
 /**
- * @exposeenum HTTPMethod
+ * @exposeenum c2.HTTPMethod
  */
 enum class NetworkRequestType {
     Get,

src/controllers/plugins/api/HTTPRequest.hpp

@@ -16,11 +16,11 @@ namespace chatterino::lua::api {
 // NOLINTBEGIN(readability-identifier-naming)
 
 /**
- * @lua@alias HTTPCallback fun(result: HTTPResponse): nil
+ * @lua@alias c2.HTTPCallback fun(result: c2.HTTPResponse): nil
  */
 
 /**
- * @lua@class HTTPRequest
+ * @lua@class c2.HTTPRequest
  */
 class HTTPRequest : public std::enable_shared_from_this<HTTPRequest>
 {
@@ -61,16 +61,16 @@ public:
     /**
      * Sets the success callback
      *
-     * @lua@param callback HTTPCallback Function to call when the HTTP request succeeds
+     * @lua@param callback c2.HTTPCallback Function to call when the HTTP request succeeds
-     * @exposed HTTPRequest:on_success
+     * @exposed c2.HTTPRequest:on_success
      */
     void on_success(sol::protected_function func);
 
     /**
      * Sets the failure callback
      *
-     * @lua@param callback HTTPCallback Function to call when the HTTP request fails or returns a non-ok status
+     * @lua@param callback c2.HTTPCallback Function to call when the HTTP request fails or returns a non-ok status
-     * @exposed HTTPRequest:on_error
+     * @exposed c2.HTTPRequest:on_error
      */
     void on_error(sol::protected_function func);
 
@@ -78,7 +78,7 @@ public:
      * Sets the finally callback
      *
      * @lua@param callback fun(): nil Function to call when the HTTP request finishes
-     * @exposed HTTPRequest:finally
+     * @exposed c2.HTTPRequest:finally
      */
     void finally(sol::protected_function func);
 
@@ -86,7 +86,7 @@ public:
      * Sets the timeout
      *
      * @lua@param timeout integer How long in milliseconds until the times out
-     * @exposed HTTPRequest:set_timeout
+     * @exposed c2.HTTPRequest:set_timeout
      */
     void set_timeout(int timeout);
 
@@ -94,7 +94,7 @@ public:
      * Sets the request payload
      *
      * @lua@param data string
-     * @exposed HTTPRequest:set_payload
+     * @exposed c2.HTTPRequest:set_payload
      */
     void set_payload(QByteArray payload);
 
@@ -103,19 +103,19 @@ public:
      *
      * @lua@param name string
      * @lua@param value string
-     * @exposed HTTPRequest:set_header
+     * @exposed c2.HTTPRequest:set_header
      */
     void set_header(QByteArray name, QByteArray value);
 
     /**
      * Executes the HTTP request
      *
-     * @exposed HTTPRequest:execute
+     * @exposed c2.HTTPRequest:execute
      */
     void execute(sol::this_state L);
     /**
      * @lua@return string
-     * @exposed HTTPRequest:__tostring
+     * @exposed c2.HTTPRequest:__tostring
      */
     QString to_string();
 
@@ -126,11 +126,11 @@ public:
     /**
      * Creates a new HTTPRequest
      *
-     * @lua@param method HTTPMethod Method to use
+     * @lua@param method c2.HTTPMethod Method to use
      * @lua@param url string Where to send the request to
      *
-     * @lua@return HTTPRequest
+     * @lua@return c2.HTTPRequest
-     * @exposed HTTPRequest.create
+     * @exposed c2.HTTPRequest.create
      */
     static std::shared_ptr<HTTPRequest> create(sol::this_state L,
                                                NetworkRequestType method,

src/controllers/plugins/api/HTTPResponse.hpp

@@ -15,7 +15,7 @@ namespace chatterino::lua::api {
 // NOLINTBEGIN(readability-identifier-naming)
 
 /**
- * @lua@class HTTPResponse
+ * @lua@class c2.HTTPResponse
  */
 class HTTPResponse
 {
@@ -38,26 +38,34 @@ public:
      * Returns the data. This is not guaranteed to be encoded using any
      * particular encoding scheme. It's just the bytes the server returned.
      * 
-     * @exposed HTTPResponse:data
+     * @lua@return string
+     * @lua@nodiscard
+     * @exposed c2.HTTPResponse:data
      */
     QByteArray data();
 
     /**
      * Returns the status code.
      *
-     * @exposed HTTPResponse:status
+     * @lua@return number|nil
+     * @lua@nodiscard
+     * @exposed c2.HTTPResponse:status
      */
     std::optional<int> status();
 
     /**
      * A somewhat human readable description of an error if such happened
-     * @exposed HTTPResponse:error
+     *
+     * @lua@return string
+     * @lua@nodiscard
+     * @exposed c2.HTTPResponse:error
      */
     QString error();
 
     /**
      * @lua@return string
-     * @exposed HTTPResponse:__tostring
+     * @lua@nodiscard
+     * @exposed c2.HTTPResponse:__tostring
      */
     QString to_string();
 };