chore(scripts): improve doc_gen.py

Author: xesdoog

CONTRIBUTING.md

@@ -0,0 +1,196 @@
+# Introduction
+
+SmallBase is a lightweight Lua framework designed to provide developers with the tools and foundations to create their own scripts, without imposing specific features.
+
+With that out of the way, thank you for considering contributing to this small project. It's people like you that make these open source projects great!
+
+## Commit Convention
+
+These are recommended, but not enforced yet. SmallBase follows similar commit guidelines to [YimMenu](https://github.com/Mr-X-GTA/YimMenu/blob/master/CONTRIBUTING.md):
+
+### Commit Structure
+
+  ```text
+  <type>(scope): <description>
+
+  [optional body]
+
+  [optional footer]
+  ```
+
+- **Types (lowercase only):**
+  - feat: New features.
+  - fix: Bug fixes.
+  - style: Feature and updates related to styling.
+  - refactor: Refactoring a specific section of the codebase.
+  - test: Everything related to testing.
+  - docs: Everything related to documentation.
+  - chore: Regular code maintenance.
+
+- **Scope:**
+  - A scope is a phrase describing parts of the code affected by the changes. For example `(translations)`.
+
+- **Body (Optional):**
+  - The commit body can provide additional contextual information. For breaking changes, the body MUST start with "BREAKING CHANGE".
+
+- **Footer (Optional):**
+  - A commit footer is used to reference issues affected by the code changes. For example: "Fixes #13". It can also be used to indicate breaking changes by starting with "BREAKING CHANGE".
+
+- **Example:**
+
+  ```text
+  fix(SomeFeature): fix constructor returning an empty object.
+  docs(Readme): document coding conventions
+  ```
+
+## Coding Standards
+
+### Annotations
+
+Annotate all enums, classes, and class methods using [LuaLS](https://luals.github.io/wiki/annotations/)'s style.
+
+Annotations are critical for readability, code completion, error checking, and automatic generation of class documentations.
+
+For comments/summaries/descriptions, you can use as many dashes as you want but please leave a space between the last dash and the text.
+
+- **Example:**
+
+    ```lua
+    -- Calculates the sum of two numbers.
+    ---@param a number The first number
+    ---@param b number The second number
+    ---@return number The sum of both numbers
+    function MyClass:Add(a, b)
+        return a + b
+    end
+    ```
+
+### Global Variables
+
+There are two ways to declare globals:
+
+1. Globals that should be serialized to JSON:
+Index SmallBase's `GVars` table. Even if the variable was never declared before:
+
+    ```lua
+    GVars.some_feature_enabled, _ = ImGui.Checkbox("My Checkbox", GVars.some_feature_enabled)
+    ```
+
+2. Regular globals:
+Use Lua's default global table `_G`:
+
+    ```lua
+    some_global_number = 123
+    ```
+
+### Style
+
+You are free to use any style you want, except in these cases:
+
+| Scope | Naming | Example |
+| ----------- | ----------- | ---------- |
+| Global Functions | PascalCase | `function DoSomething(...) end` |
+| Local Functions | any (consistent) | You are free to use any style as long as it stays consistent throughout the whole file |
+| Standard Lib Extensions | Use the lib's default style | `string.somefunc = function(...) end` |
+| Enums | PascalCase prefixed with a lowercase `e` | `eExampleEnum` |
+| Enum Members | Preferably UPPER_SNAKE_CASE but PascalCase is also allowed | `eExampleEnum.SOME_MEMBER`/`eExampleEnum.SomeMember` |
+| Classes | PascalCase | `MyNewClass = Class("MyNewClass")` |
+| Class Methods | PascalCase | `function MyNewClass:ExampleMethod(...) end` |
+| Class Private Variables | snake_case prefixed with an `m` | `m_handle` |
+
+### Formatting
+
+- **Indentations:**
+  - Does not matter. If using tabs, make sure one tab equals **four** spaces.
+
+- **Line Wrapping:**
+  - Try to wrap wide lines using either your IDE's formatter or a Pythonic way.
+
+    - Example:
+
+        ```lua
+        SomeFunc(param1, param2, param3, param4, param5, param6, param7, param8, param9, ...)
+        ```
+
+    - Preferred (Pythonic) style:
+
+        ```lua
+        SomeFunc(
+            param1,
+            param2,
+            param3,
+            param4,
+            param5,
+            param6,
+            param7,
+            param8,
+            param9,
+            ...
+        )
+        ```
+
+- **Nested `if` Statements:**
+
+  - Always try to use guarded if statements when applicable.
+
+    - Example:
+
+        ```lua
+        local cond_1 = false
+        local cond_2 = nil
+        local cond_3 = true
+
+        if cond_1 then
+            if cond_2 then
+                if cond_3 then
+                    DoSomething()
+                end
+            end
+        end
+        ```
+
+    - Preferred approach:
+
+        ```lua
+        local cond_1 = false
+        local cond_2 = nil
+        local cond_3 = true
+
+        if not cond_1 then
+            return
+        end
+
+        if not cond_2 then
+            return
+        end
+
+        if not cond_3 then
+            return
+        end
+
+        DoSomething()
+        ```
+
+    - Shorter version:
+
+        ```lua
+        local cond_1 = false
+        local cond_2 = nil
+        local cond_3 = true
+
+        if not (cond_1 and cond_2 and cond_3) then
+            return
+        end
+
+        DoSomething()
+        ```
+
+## What To Avoid
+
+Avoid adding end-user features directly to the project (example: A drift minigame, a business manager, animations, etc.).
+
+SmallBase is, as the name suggests, a base. It provides the tools and the foundations to create new scripts.
+
+Two scripts can both use this project as a template and offer completely different sets of features.
+
+If you want to share a feature, make it a standalone module that uses SmallBase.

SmallBase/includes/lib/compat.lua

@@ -1,7 +1,6 @@
 -- Basic compatibility layers/API stubs
 ---@diagnostic disable: lowercase-global
 
----@class Compat
 local Compat = {}
 Compat.__index = Compat
 

SmallBase/includes/lib/mock_env.lua

@@ -31,8 +31,8 @@ end
 
 if (not io["exists"]) then
     io.exists = function(filepath)
-        local f, _ = io.open(filepath, "r")
-        if not f then
+        local ok, f = pcall(io.open, filepath, "r")
+        if not ok or not f then
             return false
         end
 

SmallBase/includes/modules/Color.lua

@@ -3,6 +3,9 @@
 --------------------------------------
 -- Class: Color
 --------------------------------------
+-- Color instances can be created using color names defined in `Color.string_colors`,
+-- self-regsitered color names (using the `RegisterNamedColor` method),
+-- hex strings, ABGR uint_32, RGBA floats (0 - 1), and RGBA numbers (0 - 255).
 ---@class Color
 ---@overload fun(...): Color
 Color = Class("Color")
@@ -25,6 +28,7 @@ Color.string_colors = {
     ["purple"] = { 1.0, 0.0, 1.0, 1.0 },
 }
 
+---@ignore
 function Color:__tostring()
     if not self.value or not self.type then
         return string.format(
@@ -61,10 +65,12 @@ function Color:__tostring()
     )
 end
 
+---@ignore
 function Color:print()
     print(self:__tostring())
 end
 
+---@ignore
 function Color:GetValue()
     if not self.type or not self.arg or not self.arg[1] then
         return "None"
@@ -165,16 +171,14 @@ function Color.new(...)
 end
 
 -- Allows you to register new named colors in the Color class itself
---
--- that you can call later using `Color.new("your_custom_color_name")`
+-- that you can call later using `Color("your_custom_color_name")`
 --
 -- Example usage:
 --
---      Color:RegisterNamedColor("Magenta", "#FF00FF")
---
--- You can then use it like so:
---
---      local r, g, b, a = Color.new("Magenta"):AsRGBA()
+-- ```lua
+-- Color:RegisterNamedColor("Magenta", "#FF00FF")
+-- local r, g, b, a = Color("Magenta"):AsRGBA()
+-- ```
 ---@param name string
 ---@param ... any
 function Color:RegisterNamedColor(name, ...)
@@ -249,6 +253,7 @@ function Color:AsRGBA()
 end
 
 -- Returns a color in float format.
+---@return float, float, float, float
 function Color:AsFloat()
     if not self.type then
         return 0, 0, 0, 0
@@ -262,6 +267,8 @@ function Color:AsFloat()
     end
 end
 
+-- Returns a color hex string.
+---@return string|nil
 function Color:AsHex()
     if not self.type then
         return
@@ -275,7 +282,7 @@ function Color:AsHex()
     end
 end
 
--- Returns a uint32 color in **ABGR** format.
+-- Returns a uint_32 color in **ABGR** format.
 ---@return number
 function Color:AsU32()
     if not self.type then
@@ -290,14 +297,16 @@ function Color:AsU32()
     end
 end
 
+---@ignore
 function Color:serialize()
     return { __type = "color", arg = self.arg }
 end
 
+---@ignore
 function Color.deserialize(t)
     if (type(t) ~= "table" or not t.arg) then
         log.warning("[Color]: Deserialization failed: invalid data!")
-        return Color.new(0, 0, 0, 1)
+        return Color.new("black")
     end
 
     return Color.new(t.arg)

SmallBase/includes/modules/Decorator.lua

@@ -3,7 +3,7 @@
 --------------------------------------
 -- **Global Singleton.**
 --
--- - Custom decorator to mark entities owned by this script.
+-- Custom decorator to mark entities owned by this script.
 ---@class Decorator
 Decorator = {}
 Decorator.RegisteredEntities = {}

SmallBase/includes/modules/Memory.lua

@@ -1,7 +1,7 @@
 --------------------------------------
 -- Class: Memory
 --------------------------------------
---[[**Global Singleton.**]]
+--**Global Singleton.**
 ---@class Memory
 Memory = {}
 Memory.__index = Memory

SmallBase/includes/modules/Object.lua

@@ -5,7 +5,7 @@
 --
 -- **Parent:** `Entity`.
 --
--- - Class representing a GTA V object (Unfinished).
+-- Class representing a GTA V object (Unfinished).
 ---@class Object : Entity
 ---@overload fun(handle: integer): Entity
 Object = Class("Object", Entity)

SmallBase/includes/modules/Ped.lua

@@ -5,7 +5,7 @@
 --
 -- **Parent:** `Entity`.
 --
--- - Class representing a GTA V NPC.
+-- Class representing a GTA V NPC.
 ---@class Ped : Entity
 ---@field private layout CPed
 ---@field Create fun(_, modelHash: number, entityType: eEntityTypes, pos?: vec3, heading?: number, isNetwork?: boolean, isScriptHostPed?: boolean): Ped

SmallBase/includes/modules/Self.lua

@@ -7,7 +7,7 @@
 --
 -- **Parent:** `Player`.
 --
--- - Class representing the local player.
+-- Class representing the local player.
 ---@class Self: Player
 Self = Class("Self", Player)
 Self.new = nil

SmallBase/includes/modules/Time.lua

@@ -7,7 +7,7 @@
 --------------------------------------
 -- Class: Time
 --------------------------------------
--- **Global Singleton.**
+--**Global Singleton.**
 ---@class Time
 local Time = {}
 Time.__index = Time