From 6ac1e574d03be2d7d2c226d6863c2790752340f8 Mon Sep 17 00:00:00 2001
From: devclyde <israel.devclyde@protonmail.com>
Date: Thu, 23 Jun 2022 21:59:52 -0300
Subject: [PATCH] feat: add documentation for `gears.debug`

---
 lua/gears/debug/__emmylua.lua |  9 +++++
 lua/gears/debug/init.lua      | 76 +++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 lua/gears/debug/__emmylua.lua
 create mode 100644 lua/gears/debug/init.lua

diff --git a/lua/gears/debug/__emmylua.lua b/lua/gears/debug/__emmylua.lua
new file mode 100644
index 0000000..bba4f98
--- /dev/null
+++ b/lua/gears/debug/__emmylua.lua
@@ -0,0 +1,9 @@
+--- ### Description
+--- This file contains the EmmyLua based annotations for `gears.debug`, you should not use `require` in this file.
+--- @module "gears.debug.__emmylua"
+
+--#region DebugDeprecateDescriptor Definition
+
+--- @class DebugDeprecateDescriptor
+--- @field raw boolean Print the message as-is without the automatic context.
+--- @field deprecate_in integer Print the message only when Awesome's version is equal to or greater than `deprecated_in`.
diff --git a/lua/gears/debug/init.lua b/lua/gears/debug/init.lua
new file mode 100644
index 0000000..0d2e9af
--- /dev/null
+++ b/lua/gears/debug/init.lua
@@ -0,0 +1,76 @@
+--- ### Information
+--- - **Copyright**: 2010 Uli Schlachter
+--- - **Originally authored by**: Uli Schlachter
+---
+--- [See all contributors on GitHub](https://github.com/awesomeWM/awesome/graphs/contributors)
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html)
+--- @module "gears.debug"
+local GDebugging = {}
+
+--- ### Description
+--- Inspect the value in data.
+--- ### Parameters
+--- @generic TArg
+--- @generic TValue
+--- @param data TArg Value to inspect.
+--- @param tag TValue The name of the value.
+--- @param depth? integer Depth of recursion.
+--- ### Returns
+--- @return string result A string that contains the expanded value of data.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html#dump_return)
+GDebugging.dump_return = function(data, tag, depth) end
+
+--- ### Description
+--- Print the table (or any other value) to the console.
+--- ### Parameters
+--- @generic TArg
+--- @generic TValue
+--- @param data TArg Value to inspect.
+--- @param tag TValue The name of the value.
+--- @param depth? integer Depth of recursion.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html#dump)
+GDebugging.dump = function(data, tag, depth) end
+
+--- ### Description
+--- Print an warning message.
+--- ### Parameters
+--- @param message string The warning message to print.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html#print_warning)
+GDebugging.print_warning = function(message) end
+
+--- ### Description
+--- Print an error message.
+--- ### Parameters
+--- @param message string The error message to print.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html#print_error)
+GDebugging.print_error = function(message) end
+
+--- ### Description
+--- Display a deprecation notice, but only once per traceback.
+---
+--- This function also emits the `debug::deprecation` signal on the [`awesome`](https://awesomewm.org/apidoc/core_components/awesome.html#) global object.
+--- If the deprecated API has been deprecated for more than one API level, it will also send a non-fatal error.
+--- ### Parameters
+--- @param see? string  The message to a new method / function to use.
+--- @param args DebugDeprecateDescriptor Extra arguments.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html#deprecate)
+GDebugging.deprecate = function(see, args) end
+
+--- ### Description
+--- Create a class proxy with deprecation messages.
+--- This is useful when a class has moved somewhere else.
+--- ### Parameters
+--- @param fallback table The new class.
+--- @param old_name string The old class name.
+--- @param new_name string The new class name.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html#deprecate_class)
+GDebugging.deprecate_class = function(fallback, old_name, new_name) end
+
+return GDebugging