From e12a68a74d9527d4becde122da4ff1ad6550564e Mon Sep 17 00:00:00 2001
From: jacqueline <me@jacqueline.id.au>
Date: Fri, 5 Jan 2024 17:15:47 +1100
Subject: [PATCH] split lua stubs into one set for ldoc, and one set for lua-ls

---
 .luarc.json                                 |  3 +-
 config.ld                                   |  4 +--
 {src/lua/stubs => ldoc-stubs}/alerts.lua    |  0
 {src/lua/stubs => ldoc-stubs}/backstack.lua |  0
 {src/lua/stubs => ldoc-stubs}/bluetooth.lua |  9 +++---
 {src/lua/stubs => ldoc-stubs}/database.lua  |  0
 ldoc-stubs/playback.lua                     | 19 ++++++++++++
 ldoc-stubs/power.lua                        | 18 +++++++++++
 ldoc-stubs/queue.lua                        | 22 ++++++++++++++
 {src/lua/stubs => ldoc-stubs}/types.lua     | 12 ++++++--
 ldoc-stubs/volume.lua                       | 14 +++++++++
 luals-stubs/alerts.lua                      | 11 +++++++
 luals-stubs/backstack.lua                   | 11 +++++++
 luals-stubs/bluetooth.lua                   |  8 +++++
 luals-stubs/database.lua                    | 33 +++++++++++++++++++++
 luals-stubs/playback.lua                    | 10 +++++++
 luals-stubs/power.lua                       | 10 +++++++
 luals-stubs/queue.lua                       | 11 +++++++
 luals-stubs/types.lua                       | 13 ++++++++
 luals-stubs/volume.lua                      |  8 +++++
 src/lua/stubs/playback.lua                  | 15 ----------
 src/lua/stubs/power.lua                     | 18 -----------
 src/lua/stubs/queue.lua                     | 22 --------------
 src/lua/stubs/volume.lua                    | 14 ---------
 24 files changed, 206 insertions(+), 79 deletions(-)
 rename {src/lua/stubs => ldoc-stubs}/alerts.lua (100%)
 rename {src/lua/stubs => ldoc-stubs}/backstack.lua (100%)
 rename {src/lua/stubs => ldoc-stubs}/bluetooth.lua (67%)
 rename {src/lua/stubs => ldoc-stubs}/database.lua (100%)
 create mode 100644 ldoc-stubs/playback.lua
 create mode 100644 ldoc-stubs/power.lua
 create mode 100644 ldoc-stubs/queue.lua
 rename {src/lua/stubs => ldoc-stubs}/types.lua (81%)
 create mode 100644 ldoc-stubs/volume.lua
 create mode 100644 luals-stubs/alerts.lua
 create mode 100644 luals-stubs/backstack.lua
 create mode 100644 luals-stubs/bluetooth.lua
 create mode 100644 luals-stubs/database.lua
 create mode 100644 luals-stubs/playback.lua
 create mode 100644 luals-stubs/power.lua
 create mode 100644 luals-stubs/queue.lua
 create mode 100644 luals-stubs/types.lua
 create mode 100644 luals-stubs/volume.lua
 delete mode 100644 src/lua/stubs/playback.lua
 delete mode 100644 src/lua/stubs/power.lua
 delete mode 100644 src/lua/stubs/queue.lua
 delete mode 100644 src/lua/stubs/volume.lua

diff --git a/.luarc.json b/.luarc.json
index eae0da56..a0e9e1b7 100644
--- a/.luarc.json
+++ b/.luarc.json
@@ -1,6 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
-  "workspace.library": ["lib/luavgl/src", "src/lua/stubs"],
+  "workspace.library": ["lib/luavgl/src", "luals-stubs"],
+  "workspace.ignoreDir": ["ldoc-stubs"],
   "runtime.version": "Lua 5.4",
 }
 
diff --git a/config.ld b/config.ld
index a705ca05..e1c54172 100644
--- a/config.ld
+++ b/config.ld
@@ -1,3 +1,3 @@
-file = {'src/lua/stubs'}
+file = {'ldoc-stubs'}
 project = "Tangara"
-description = "Lua modules provided by Tangara's firmware"
\ No newline at end of file
+description = "Lua modules provided by Tangara's firmware"
diff --git a/src/lua/stubs/alerts.lua b/ldoc-stubs/alerts.lua
similarity index 100%
rename from src/lua/stubs/alerts.lua
rename to ldoc-stubs/alerts.lua
diff --git a/src/lua/stubs/backstack.lua b/ldoc-stubs/backstack.lua
similarity index 100%
rename from src/lua/stubs/backstack.lua
rename to ldoc-stubs/backstack.lua
diff --git a/src/lua/stubs/bluetooth.lua b/ldoc-stubs/bluetooth.lua
similarity index 67%
rename from src/lua/stubs/bluetooth.lua
rename to ldoc-stubs/bluetooth.lua
index 2fba1ec6..3160ef7e 100644
--- a/src/lua/stubs/bluetooth.lua
+++ b/ldoc-stubs/bluetooth.lua
@@ -1,14 +1,13 @@
 --- Properties and functions for handling Bluetooth connectivity
 -- @module bluetooth
-
 local bluetooth = {}
 
 --- Whether or not the Bluetooth stack is currently enabled. This property is writeable, and can be used to enable or disable Bluetooth.
--- @treturn types.Property a boolean property
-function bluetooth.enabled() end
+-- @see types.Property
+bluetooth.enabled = types.Property
 
 --- Whether or not there is an active connection to another Bluetooth device.
--- @treturn types.Property a boolean property
-function bluetooth.connected() end
+-- @see types.Property
+bluetooth.connected = types.Property
 
 return bluetooth
diff --git a/src/lua/stubs/database.lua b/ldoc-stubs/database.lua
similarity index 100%
rename from src/lua/stubs/database.lua
rename to ldoc-stubs/database.lua
diff --git a/ldoc-stubs/playback.lua b/ldoc-stubs/playback.lua
new file mode 100644
index 00000000..07ed65f6
--- /dev/null
+++ b/ldoc-stubs/playback.lua
@@ -0,0 +1,19 @@
+--- Properties for interacting with the audio playback system
+-- @module playback
+
+local playback = {}
+
+--- Whether or not any audio is *allowed* to be played. If there is a current track, then this is essentially an indicator of whether playback is paused or unpaused.
+-- @see types.Property
+playback.playing = types.Property
+
+--- Rich information about the currently playing track.
+-- @see types.Property
+-- @see types.Track
+playback.track = types.Property
+
+--- The current playback position within the current track, in seconds.
+-- @see types.Property
+playback.position = types.Property
+
+return playback
diff --git a/ldoc-stubs/power.lua b/ldoc-stubs/power.lua
new file mode 100644
index 00000000..466cafed
--- /dev/null
+++ b/ldoc-stubs/power.lua
@@ -0,0 +1,18 @@
+--- Properties and functions that deal with the device's battery and power state
+-- @module power
+
+local power = {}
+
+--- The battery's current charge as a percentage
+-- @see types.Property
+power.battery_pct = types.Property
+
+--- The battery's current voltage, in millivolts.
+-- @see types.Property
+power.battery_millivolts = types.Property
+
+--- Whether or not the device is currently receiving external power
+-- @see types.Property
+power.plugged_in = types.Property
+
+return power
diff --git a/ldoc-stubs/queue.lua b/ldoc-stubs/queue.lua
new file mode 100644
index 00000000..83849624
--- /dev/null
+++ b/ldoc-stubs/queue.lua
@@ -0,0 +1,22 @@
+--- Properties and functions for inspecting and manipulating the track playback queue
+-- @module queue
+
+local queue = {}
+
+--- The index in the queue of the currently playing track. This may be zero if the queue is empty.
+-- @see types.Property
+queue.position = types.Property
+
+--- The total number of tracks in the queue, including tracks which have already been played.
+-- @see types.Property
+queue.size = types.Property
+
+--- Determines whether or not the queue will be restarted after the final track is played.
+-- @see types.Property
+queue.replay = types.Property
+
+--- Determines whether, when progressing to the next track in the queue, the next track will be chosen randomly. The random selection algorithm used is a Miller Shuffle, which guarantees that no repeat selections will be made until every item in the queue has been played.
+-- @see types.Property
+queue.random = types.Property
+
+return queue
diff --git a/src/lua/stubs/types.lua b/ldoc-stubs/types.lua
similarity index 81%
rename from src/lua/stubs/types.lua
rename to ldoc-stubs/types.lua
index 1f6970bd..3480610c 100644
--- a/src/lua/stubs/types.lua
+++ b/ldoc-stubs/types.lua
@@ -1,10 +1,11 @@
 --- Userdata-based types used throughout the rest of the API. These types are
 --- not generally constructable within Lua code.
 -- @module types
+local types = {}
 
---- A value sourced from the C++ firmware.
+--- A observable value, owned by the C++ firmware.
 -- @type Property
-local Property = {}
+types.Property = {}
 
 --- Gets the current value
 -- @return The property's current value.
@@ -24,4 +25,11 @@ function Property:set(val) end
 -- @return fn, for more ergonmic use with anonymous closures.
 function Property:bind(fn) end
 
+--- Table containing information about a track. Most fields are optional.
+-- @type Track
+types.Track = {}
+
+--- The title of the track, or the filename if no title is available.
+types.Track.title = ""
+
 return Property
diff --git a/ldoc-stubs/volume.lua b/ldoc-stubs/volume.lua
new file mode 100644
index 00000000..7eff24c5
--- /dev/null
+++ b/ldoc-stubs/volume.lua
@@ -0,0 +1,14 @@
+--- Module for interacting with playback volume. The Bluetooth and wired outputs store their current volume separately; this API only allows interacting with the volume of the currently used output device.
+-- @module volume
+
+local volume = {}
+
+--- The current volume as a percentage of the current volume limit.
+-- @see types.Property
+volume.current_pct = types.Property
+
+--- The current volume in terms of decibels relative to line level.
+-- @see types.Property
+volume.current_db = types.Property
+
+return volume
diff --git a/luals-stubs/alerts.lua b/luals-stubs/alerts.lua
new file mode 100644
index 00000000..d430f12d
--- /dev/null
+++ b/luals-stubs/alerts.lua
@@ -0,0 +1,11 @@
+--- @meta 
+
+--- @class alerts
+local alerts = {}
+
+--- @param constructor function
+function alerts.show(constructor) end
+
+function alerts.hide() end
+
+return alerts
diff --git a/luals-stubs/backstack.lua b/luals-stubs/backstack.lua
new file mode 100644
index 00000000..2e4eccb3
--- /dev/null
+++ b/luals-stubs/backstack.lua
@@ -0,0 +1,11 @@
+--- @meta
+
+--- @class backstack
+local backstack = {}
+
+--- @param constructor function
+function backstack.push(constructor) end
+
+function backstack.pop() end
+
+return backstack
diff --git a/luals-stubs/bluetooth.lua b/luals-stubs/bluetooth.lua
new file mode 100644
index 00000000..09fc7606
--- /dev/null
+++ b/luals-stubs/bluetooth.lua
@@ -0,0 +1,8 @@
+--- @meta
+
+--- @class bluetooth
+--- @field enabled Property
+--- @field connected Property
+local bluetooth = {}
+
+return bluetooth
diff --git a/luals-stubs/database.lua b/luals-stubs/database.lua
new file mode 100644
index 00000000..e23c085b
--- /dev/null
+++ b/luals-stubs/database.lua
@@ -0,0 +1,33 @@
+--- @meta
+
+--- @class database
+local database = {}
+
+--- @return Index[]
+function database.indexes() end
+
+--- @class Iterator
+local Iterator = {}
+
+--- @class TrackId
+local TrackId = {}
+
+--- @class Record
+local Record = {}
+
+--- @return string
+function Record:title() end
+
+--- @return TrackId|Iterator(Record)
+function Record:contents() end
+
+--- @class Index
+local Index = {}
+
+--- @return string
+function Index:name() end
+
+--- @return Iterator(Record)
+function Index:iter() end
+
+return database
diff --git a/luals-stubs/playback.lua b/luals-stubs/playback.lua
new file mode 100644
index 00000000..cd54ddb3
--- /dev/null
+++ b/luals-stubs/playback.lua
@@ -0,0 +1,10 @@
+--- @meta
+
+--- Properties for interacting with the audio playback system
+--- @class playback
+--- @field playing Property Whether or not audio is allowed to be played. if there is a current track, then this indicated whether playback is paused or unpaused. If there is no current track, this determines what will happen when the first track is added to the queue.
+--- @field track Property The currently playing track.
+--- @field position Property The current playback position within the current track, in seconds.
+local playback = {}
+
+return playback
diff --git a/luals-stubs/power.lua b/luals-stubs/power.lua
new file mode 100644
index 00000000..226f8200
--- /dev/null
+++ b/luals-stubs/power.lua
@@ -0,0 +1,10 @@
+--- @meta
+
+--- Properties and functions that deal with the device's battery and power state.
+--- @class power
+--- @field battery_pct Property The battery's current charge, as a percentage of the maximum charge.
+--- @field battery_millivolts Property The battery's current voltage, in millivolts.
+--- @field plugged_in Property Whether or not the device is currently receiving external power.
+local power = {}
+
+return power
diff --git a/luals-stubs/queue.lua b/luals-stubs/queue.lua
new file mode 100644
index 00000000..0c63b8c1
--- /dev/null
+++ b/luals-stubs/queue.lua
@@ -0,0 +1,11 @@
+--- @meta
+
+--- Properties and functions for inspecting and manipulating the track playback queue
+--- @class queue
+--- @field position Property The index in the queue of the currently playing track. This may be zero if the queue is empty. Writeable.
+--- @field size Property The total number of tracks in the queue, including tracks which have already been played.
+--- @field replay Property Whether or not the queue will be restarted after the final track is played. Writeable.
+--- @field random Property  Determines whether, when progressing to the next track in the queue, the next track will be chosen randomly. The random selection algorithm used is a Miller Shuffle, which guarantees that no repeat selections will be made until every item in the queue has been played. Writeable.
+local queue = {}
+
+return queue
diff --git a/luals-stubs/types.lua b/luals-stubs/types.lua
new file mode 100644
index 00000000..ecfee29b
--- /dev/null
+++ b/luals-stubs/types.lua
@@ -0,0 +1,13 @@
+--- @meta
+
+---@class Property
+local property = {}
+
+function property:get() end
+
+function property:set(val) end
+
+--- @param fn function
+function property:bind(fn) end
+
+return property
diff --git a/luals-stubs/volume.lua b/luals-stubs/volume.lua
new file mode 100644
index 00000000..42d65884
--- /dev/null
+++ b/luals-stubs/volume.lua
@@ -0,0 +1,8 @@
+--- @meta
+
+--- @class volume
+--- @field current_pct Property
+--- @field current_db Property
+local volume = {}
+
+return volume
diff --git a/src/lua/stubs/playback.lua b/src/lua/stubs/playback.lua
deleted file mode 100644
index 340da37d..00000000
--- a/src/lua/stubs/playback.lua
+++ /dev/null
@@ -1,15 +0,0 @@
---- Properties for interacting with the audio playback system
--- @module playback
-
-local playback = {}
-
---- Whether or not any audio is *allowed* to be played. If there is a current track, then this is essentially an indicator of whether playback is paused or unpaused.
---- This value isn't meaningful if there is no current track.
--- @treturn types.Property a boolean property
-function playback.playing() end
-
-function playback:track() end
-
-function playback:position() end
-
-return playback
diff --git a/src/lua/stubs/power.lua b/src/lua/stubs/power.lua
deleted file mode 100644
index 30fe7520..00000000
--- a/src/lua/stubs/power.lua
+++ /dev/null
@@ -1,18 +0,0 @@
---- Properties and functions that deal with the device's battery and power state
--- @module power
-
-local power = {}
-
---- battery_pct returns the battery's current charge as a percentage
--- @treturn types.Property an integer property, from 0 to 100
-function power.battery_pct() end
-
---- battery_millivolts returns the battery's current voltage in millivolts
--- @treturn types.Property an integer property, typically from about 3000 to about 4200.
-function power.battery_millivolts() end
-
---- plugged_in returns whether or not the device is currently receiving external power
--- @treturn types.Property a boolean property
-function power.plugged_in() end
-
-return power
\ No newline at end of file
diff --git a/src/lua/stubs/queue.lua b/src/lua/stubs/queue.lua
deleted file mode 100644
index 000c35d3..00000000
--- a/src/lua/stubs/queue.lua
+++ /dev/null
@@ -1,22 +0,0 @@
---- Properties and functions for inspecting and manipulating the track playback queue
--- @module queue
-
-local queue = {}
-
---- queue.position returns the index in the queue of the currently playing track. This may be zero if the queue is empty.
--- @treturn types.Property a positive integer property, which is a 1-based index
-function queue.position() end
-
---- queue.size returns the total number of tracks in the queue, including tracks which have already been played.
--- @treturn types.Property a positive integer property
-function queue.size() end
-
---- queue.replay determines whether or not the queue will be restarted after the final track is played.
--- @treturn types.Property a writeable boolean property
-function queue.replay() end
-
---- queue.random determines whether, when progressing to the next track in the queue, the next track will be chosen randomly. The random selection algorithm used is a Miller Shuffle, which guarantees that no repeat selections will be made until every item in the queue has been played.
--- @treturn types.Property a writeable boolean property
-function queue.random() end
-
-return queue
\ No newline at end of file
diff --git a/src/lua/stubs/volume.lua b/src/lua/stubs/volume.lua
deleted file mode 100644
index 15499630..00000000
--- a/src/lua/stubs/volume.lua
+++ /dev/null
@@ -1,14 +0,0 @@
---- Module for interacting with playback volume. The Bluetooth and wired outputs store their current volume separately; this API only allows interacting with the volume of the currently used output device.
--- @module volume
-
-local volume = {}
-
---- Returns the current volume as a percentage of the current volume limit.
--- @treturn types.Property an integer property
-function volume.current_pct() end
-
---- Returns the current volume in terms of dB from line level.
--- @treturn types.Property an integer property
-function volume.current_db() end
-
-return volume