Merge pull request #56 from adrianocastro189/release/version-1.3.0

Release - v1.3.0

.gitignore

@@ -1,2 +1,3 @@
 /dist/*
+.videos
 .vscode

README.md

@@ -4,13 +4,21 @@ A library developed in Lua to serve as a framework for building World of Warcraf
 
 # Documentation
 
-Stormwind Library documentation is built on top of [docusaurus](https://docusaurus.io/).
+Stormwind Library documentation is built on top of [docusaurus](https://docusaurus.io/)
+and is available [here](https://www.stormwindlibrary.com).
 
-Steps to host and see the documentation locally:
+These are the steps to host and see the documentation locally:
 
 * Make sure you have [Node.js](https://nodejs.org/en/download/) version 18.0 or above
 * Make sure `npx` command is available, version 9.0 or above
 * Go to the **documentation** folder
 * If working on a fresh cloned repository, run `npm install`
 * Run `npx docusaurus start`
-* Open the browser and navigate to [localhost:3000](http://localhost:3000/) (or port 3001 if 3000 is occupied, and so on...)
+* Open the browser and navigate to [localhost:3000](http://localhost:3000/) (or port 3001 if 3000 is occupied, and so on...)
+
+## ❤️ Support this project
+
+If you like this framework and want to support its development, you can
+[buy the author a coffee](https://github.com/sponsors/adrianocastro189).
+
+Every contribution or subscription is deeply appreciated.

compiler/build.js

@@ -37,7 +37,7 @@ class StormwindLibrary {
 
         // adds a new line to avoid having the last comment in a file to be just before the
         // first comment in the imported file, resulting in a single comment block and messing
-        // up the Lua Doc generation.
+        // up the LuaDoc generation.
         fileContent += '\n';
 
         // replaces the file content import line with the file contents

config.ld

@@ -1,10 +1,12 @@
-function postprocess_html(html)
+-- uncomment the following line if this is needed in the future
+-- function postprocess_html(html)
     -- removes the "last updated <i> tag at the documentation folder
     -- example: <i style="float:right;">Last updated 2024-04-27 16:27:57 </i>
     -- this is good to avoid many .html changes for each commit when the ldoc
     -- generator is executed
-    return html:gsub('<i%s+style="float:right;">Last%s+updated%s+[%d%-: ]+%s+</i>\n', '')
-end
+    -- return html:gsub('<i%s+style="float:right;">Last%s+updated%s+[%d%-: ]+%s+</i>\n', '')
+-- end
 
 sort=true
-postprocess_html=postprocess_html
+-- uncomment the following line if this is needed in the future
+-- postprocess_html=postprocess_html

documentation/docs/changelog.md

@@ -1,6 +1,17 @@
 # Changelog
 
-## yyyy.mm.dd - version 1.2.0
+## 2024.05.24 - version 1.3.0
+
+* Documentation published on [GitHub Pages](https://www.stormwindlibrary.com)
+* Finish covering all classes with LuaDoc blocks
+* Fix Events:notify() to properly handle multiple arguments
+* Move the dd() method to a better location in the library structure, 
+allowing it to be used before the Output class is registered
+* Move the generated LuaDoc files inside the docusaurus folder
+* Move World of Warcraft API mocks to a new reusable file separated from 
+the unit suite
+
+## 2024.05.08 - version 1.2.0
 
 * Add the Environment class to identify the environment where the addon is 
 running
@@ -24,7 +35,7 @@ World of Warcraft versions if necessary
 * Add a "dump and die" method to the Output class to improve debugging
 * Add a new property to initialize the library that allows addons to have a 
 class managing configurations and settings with facades to Arr
-* Add more Lua Doc blocks covering the library structure: to all classes in 
+* Add more LuaDoc blocks covering the library structure: to all classes in 
 the Commands structure, and to Output
 * Add the Configuration class to handle addon configurations and settings
 * Add the library getClass() method to allow addons to retrieve a class 

documentation/docs/library-structure/docs.md

@@ -0,0 +1,52 @@
+# Documentation
+
+The Stormwind Library documentation is built on top of
+[Docusaurus](https://docusaurus.io/) and is hosted on
+[GitHub Pages](https://pages.github.com/).
+
+When working on any part of the library, it is important to keep the documentation
+up-to-date. This includes updating the documentation for any new features or changes
+that are made to the library.
+
+## Documentation deployment process
+
+**Single time setup**
+
+Although the following steps need to be done only once, it is important to keep them 
+documented in case the library is moved to a new repository or even if it requires some
+additional page in the future.
+
+1. Open the `documentation\docusaurus.config.js` file and update the following properties:
+   * `url` - `'https://adrianocastro189.github.io'`
+   * `baseUrl` - `'/stormwind-library/'`
+   * `projectName` - `'stormwind-library'`
+   * `organizationName` - `'adrianocastro189'`
+1. Open the terminal
+1. Navigate to the `documentation` directory and run
+   ```shell
+   npm run build
+   ```
+1. Confirm that the `documentation/build` directory was created
+1. Install `gh-pages` with the following command:
+   ```shell
+   npm install --save-dev gh-pages
+   ```
+1. Open `documentation\package.json` and update the `scripts.deploy` property to:
+   ```json
+   "deploy": "gh-pages -d build"
+   ```
+1. Run the deployment command described after these steps
+1. Go to [GitHub Pages](https://github.com/adrianocastro189/stormwind-library/settings/pages)
+1. Select **Deploy from a branch** and choose the `gh-pages` branch (root directory)
+1. Click save
+
+**Deploying the documentation**
+
+1. Open the terminal
+1. Navigate to the `documentation` directory and run
+   ```shell
+   npm run build
+   npm run deploy
+   ```
+1. If running it for the first time, make sure to check if a `gh-pages` branch was created
+and pushed to the repository

documentation/docs/library-structure/luadocs.md

@@ -1,4 +1,4 @@
-# Lua Docs
+# LuaDocs
 
 Although the Stormwind Library is fully covered in this documentation page 
 built over Docusaurus, the technical documentation is not well described
@@ -63,7 +63,7 @@ The documentation standards are based on the
 
 However, there are some rules that are not covered by the manual, so
 these are a couple of standards that are used in the Stormwind Library
-Lua doc blocks:
+LuaDoc blocks:
 
 1. Class and methods blocks use the `--[[--` doc block style.
 1. The `@classmod` tag is used to define the class name and due to how the library is 
@@ -81,6 +81,10 @@ when they should not be used outside the class.
       * Prefer to not break lines, even if the line is longer than the current
         sizes as observed in other classes, unless it's really necessary by
         being too long or having multiple phrases.
+      * Capitalize the first word describing the parameter or return type.
+      * When using multiple types, separate them by a `|` character and prefer
+        to sort them alphabetically, except when one of the types is `nil`, 
+        which should be the last one, example: `number|string|nil`.
    * Prefer `integer` over `number` when the value must be an integer.
    * Prefer `boolean` over `bool`.
    * Use `any` when the type is not defined.
@@ -94,13 +98,35 @@ standards become more clear.
 
 ## Generated docs
 
-The technical documentation for the Stormwind library is generated in the
-`./documentation-ldoc` folder with the command:
+The technical documentation for the Stormwind Library is generated inside the 
+docusaurus' `documentation/static/lua-docs` folder and it's available
+[here](pathname:///lua-docs/index.html).
 
 ```shell
 # this command must be run from the ./dist folder
-ldoc stormwind-library.lua -d ../documentation-ldoc -c ../config.ld -v --multimodule --all
+ldoc stormwind-library.lua -d ../documentation/static/lua-docs -c ../config.ld -v --multimodule --all
 ```
 
 As of now, the generated documentation is being pushed to the repository,
-but that can be changed in the future.
+but that can be changed in the future.
+
+:::danger Linking to the generated docs
+
+When the Docusaurus task generates the `build` folder, it will copy the generated 
+technical Lua documentation from the `static/lua-docs` folder, which means they'll
+become available as a valid URL.
+
+**However**, when linking to those HTML files, it's important to use a different type
+of [link](https://docusaurus.io/docs/advanced/routing#escaping-from-spa-redirects),
+otherwise, even as a valid link, the page will result as a 404 page **when clicked
+from any page**, accessible only by typing the URL directly in the browser.
+
+When linking to the generated Lua documentation, use the following pattern:
+
+```markdown
+[click here...](pathname:///lua-docs/index.html)
+```
+
+Of course, the link above is valid for any other HTML in the `static` folder.
+
+:::

documentation/docs/resources/core/configuration.md

@@ -35,7 +35,7 @@ After that, the addon can access the configuration properties using the
 Configuration setters and getters.
 
 **Note:** For a detailed explanation of the Configuration accessors, read the
-[technical documentation](../../library-structure/luadocs#generated-docs).
+[technical documentation](pathname:///lua-docs/classes/Core.Configuration.html).
 
 ```lua
 local configTable = {}
@@ -69,7 +69,7 @@ local config = library:new('Configuration', MyAddon_Data)
 ## Accessing the configuration
 
 The Configuration class offers a set of methods to access the configuration
-properties. Those are better explained in the [technical documentation](../../library-structure/luadocs#generated-docs)
+properties. Those are better explained in the [technical documentation](pathname:///lua-docs/classes/Core.Configuration.html)
 and should be used only if the addon needs to have multiple configurations
 tables.
 

documentation/docs/resources/core/output.md

@@ -105,13 +105,13 @@ lu.assertTrue(library.output:printed('Hello, World of Warcraft!'))
 
 ## Dump and dying - dd()
 
-The `Output:dd()` method is inspired by PHP Laravel's `dd()` function and 
-offers a quick way to dump a variable and stop the execution of the script.
-It's intended to be used for debugging purposes only.
+The library's `dd()` function is inspired by PHP Laravel's `dd()` function 
+and offers a quick way to dump variables and stop the execution of the 
+script. **It's intended to be used for debugging purposes only.**
 
-Once called with one or more variables, it will print the variable structure
-using the standard `print()`, which **can't be replaced** like the 
-`Output:print()` method, considering that `dd()` is intended for debugging
+Once called with one or more variables, it will print the their structures 
+using the standard `print()` method, which **can't be replaced** like 
+`Output:print()`, considering that `dd()` is intended for debugging 
 purposes only.
 
 This method is also prepared to avoid circular references and won't break if
@@ -126,8 +126,5 @@ is recommended for small tables and variables and mostly for local testing.
 local myTable = { key = 'value' }
 
 -- this will print the table and stop the execution
-library.output:dd(myTable)
-
--- it's also possible to use the dd() method in the library global scope
 library:dd(myTable)
 ```

documentation/docs/resources/models/item.md

@@ -12,4 +12,4 @@ released and new features are implemented in the library.
 
 For a more detailed explanation of the Item model and its available methods 
 and properties, please refer to the library
-[technical documentation](../../library-structure/luadocs#generated-docs).
+[technical documentation](pathname:///lua-docs/classes/Models.Item.html).

documentation/docs/resources/models/player.md

@@ -12,7 +12,7 @@ the library.
 
 For a more detailed explanation of the Player model and its available methods 
 and properties, please refer to the library
-[technical documentation](../../library-structure/luadocs#generated-docs).
+[technical documentation](pathname:///lua-docs/classes/Models.Player.html).
 
 ## Getting the current player instance
 

documentation/docs/resources/models/realm.md

@@ -11,7 +11,7 @@ released and new features are implemented in the library.
 
 For a more detailed explanation of the Realm model and its available methods 
 and properties, please refer to the library
-[technical documentation](../../library-structure/luadocs#generated-docs).
+[technical documentation](pathname:///lua-docs/classes/Models.Realm.html).
 
 ## Getting the current realm instance
 

documentation/docs/resources/support/arr.md

@@ -100,5 +100,5 @@ experience and making it clear that the table is a list of constants.
 
 ## Methods
 
-Please, refer to the [technical documentation](../../library-structure/luadocs#generated-docs)
+Please, refer to the [technical documentation](pathname:///lua-docs/classes/Support.Arr.html)
 to get more information about this class and its methods.

documentation/docs/resources/support/bool.md

@@ -9,5 +9,5 @@ reference.
 
 ## Methods
 
-Please, refer to the [technical documentation](../../library-structure/luadocs#generated-docs)
+Please, refer to the [technical documentation](pathname:///lua-docs/classes/Support.Bool.html)
 to get more information about this class and its methods.

documentation/docs/resources/support/str.md

@@ -8,5 +8,5 @@ reference.
 
 ## Methods
 
-Please, refer to the [technical documentation](../../library-structure/luadocs#generated-docs)
+Please, refer to the [technical documentation](pathname:///lua-docs/classes/Support.Str.html)
 to get more information about this class and its methods.

documentation/docs/testing/api-mocks.md

@@ -0,0 +1,34 @@
+# API Mocks
+
+The `tests/wow-mocks.lua` file contains a set of mocks for the World of 
+Warcraft API. These mocks are used to simulate the behavior of the WoW API in 
+a controlled environment, allowing addon developers to test their code 
+without needing to run the game.
+
+It's important to note that these mocks are not a complete replacement for
+the WoW API nor behave like it. They are designed to provide a way to assert
+that addons are interacting with the WoW API correctly.
+
+As an example, it shouldn't be expected that events will be fired in the same
+way they're fired in the game when listeners are registered to frames. It's
+just a way to assert that the addon registers the listener correctly, and 
+that's all for now.
+
+:::note Look out for future implementations
+
+Although the API Mocks are just a way to make a consistent environment for
+testing, there are plans to make them more robust and closer to the real
+WoW API in a way that they can provide more values to the tests.
+
+Keep an eye on the updates to see what's new in the API Mocks.
+
+:::
+
+## Usage
+
+To use the API Mocks in your tests, simply copy the `tests/wow-mocks.lua` file
+to the `tests` directory of the addon.
+
+Feel free to add more mocks, especially to the frame methods, as they are
+the most used in the addons. Also, feel free to [open a PR](https://github.com/adrianocastro189/stormwind-library/fork)
+with the new mocks so they can be shared with the community.

documentation/docs/testing/test-classes.md

@@ -66,4 +66,7 @@ method in the test case.
 There's no need to revert the mocked properties and methods back to their
 original values after the test case is run, unless the test method is
 expected to be called multiple times in the same test class and with
-different mocks.
+different mocks.
+
+Stormwind Library also provides a set of mocks for the World of Warcraft API
+that are better described in the [API Mocks](api-mocks) documentation.

documentation/docs/testing/unit-suite.md

@@ -1,7 +1,4 @@
----
-sidebar_position: 1
-title: Unit Suite
----
+# Unit Suite
 
 :::note Lua version