Use luals-stubs as the source of truth for docs, instead of maintaining

separate docs stubs

Includes introducing a cool new script to turn lua-language-server's
json output into markdown documentation.

luals-stubs/alerts.lua

@@ -1,11 +1,15 @@
 --- @meta 
 
+--- The `alerts` module contains functions for showing transient popups over
+--- the current screen.
 --- @class alerts
 local alerts = {}
 
---- @param constructor function
+--- Shows a new alert, replacing any other alerts.
+--- @param constructor function Called to create the UI for the alert. A new default root object and group will be set before calling this function.i Alerts are non-interactable; the group created for the constructor will not be granted focus.
 function alerts.show(constructor) end
 
+--- Dismisses any visible alerts, removing them from the screen.
 function alerts.hide() end
 
 return alerts

luals-stubs/backstack.lua

@@ -1,11 +1,20 @@
 --- @meta
 
+--- The `backstack` module contains functions that can be used to implement a
+--- basic stack-based navigation hierarchy. See also the `screen` module, which
+--- provides a class prototype meant for use with this module.
 --- @class backstack
 local backstack = {}
 
---- @param constructor function
-function backstack.push(constructor) end
+--- Displays the given screen to the user. If there was already a screen being
+--- displayed, then the current screen is removed from the display, and added
+--- to the backstack.
+--- @param screen screen The screen to display.
+function backstack.push(screen) end
 
+--- Removes the current screen from the display, then replaces it with the
+--- screen that is at the top of the backstack. This function does nothing if
+--- there are no other screens in the stack.
 function backstack.pop() end
 
 return backstack

luals-stubs/bluetooth.lua

@@ -1,8 +1,12 @@
 --- @meta
 
+--- The 'bluetooth' module contains Properties and functions for interacting
+--- with the device's Bluetooth capabilities.
 --- @class bluetooth
---- @field enabled Property
---- @field connected Property
+--- @field enabled Property Whether or not the Bluetooth stack is currently enabled. This property is writeable, and can be used to enable or disable Bluetooth.
+--- @field connected Property Whether or not there is an active connection to another Bluetooth device.
+--- @field paired_device Property The device that is currently paired. The bluetooth stack will automatically connected to this device if possible.
+--- @field devices Property Devices nearby that have been discovered.
 local bluetooth = {}
 
 return bluetooth

luals-stubs/controls.lua

@@ -0,0 +1,12 @@
+--- @meta
+
+--- The `controls` module contains Properties relating to the device's physical
+--- controls. These controls include the touchwheel, the lock switch, and the
+--- side buttons.
+--- @class controls
+--- @field scheme Property The currently configured control scheme
+--- @field scroll_sensitivity Property How much rotational motion is required on the touchwheel per scroll tick.
+--- @field lock_switch Property  The current state of the device's lock switch.
+local controls = {}
+
+return controls

luals-stubs/database.lua

@@ -1,33 +1,60 @@
 --- @meta
 
+--- The `database` module contains Properties and functions for working with
+--- the device's LevelDB-backed track database.
 --- @class database
+--- @field updating Property Whether or not a database re-index is currently in progress.
 local database = {}
 
+--- Returns a list of all indexes in the database.
 --- @return Index[]
 function database.indexes() end
 
+--- An iterator is a userdata type that behaves like an ordinary Lua iterator.
 --- @class Iterator
 local Iterator = {}
 
+--- A TrackId is a unique identifier, representing a playable track in the
+--- user's library.
 --- @class TrackId
 local TrackId = {}
 
+--- Gets the human-readable text representing this record. The `__tostring`
+--- metatable function is an alias of this function.
 --- @class Record
 local Record = {}
 
 --- @return string
 function Record:title() end
 
---- @return TrackId|Iterator(Record)
+--- Returns the value that this record represents. This may be either a track
+--- id, for records which uniquely identify a track, or it may be a new
+--- Iterator representing the next level of depth for the current index.
+---
+--- For example, each Record in the "All Albums" index corresponds to an entire
+--- album of tracks; the 'contents' of such a Record is an iterator returning
+--- each track in the album represented by the Record. The contents of each of
+--- the returned 'track' Records would be a full Track, as there is no further
+--- disambiguation needed.
+--- @return TrackId|Iterator r A track id if this is a leaf record, otherwise a new iterator for the next level of this index.
 function Record:contents() end
 
+--- An index is heirarchical, sorted, view of the tracks within the database.
+--- For example, the 'All Albums' index contains, first, a sorted list of every
+--- album name in the library. Then, at the second level of the index, a sorted
+--- list of every track within each album.
 --- @class Index
 local Index = {}
 
+--- Gets the human-readable name of this index. This is typically something
+--- like "All Albums", or "Albums by Artist". The `__tostring` metatable
+--- function is an alias of this function.
 --- @return string
 function Index:name() end
 
---- @return Iterator(Record)
+--- Returns a new iterator that can be used to access every record within the
+--- first level of this index.
+--- @return Iterator it An iterator that yields `Record`s.
 function Index:iter() end
 
 return database

luals-stubs/display.lua

@@ -0,0 +1,9 @@
+--- @meta
+
+--- The `display` module contains Properties relating to the device's physical
+--- display.
+--- @class display
+--- @field brightness Property The screen's current brightness, as a gamma-corrected percentage value from 0 to 100.
+local display = {}
+
+return display

luals-stubs/playback.lua

@@ -1,6 +1,7 @@
 --- @meta
 
---- Properties for interacting with the audio playback system
+--- The `playback` module contains Properties and functions for interacting
+--- the device's audio pipeline.
 --- @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.

luals-stubs/power.lua

@@ -1,6 +1,7 @@
 --- @meta
 
---- Properties and functions that deal with the device's battery and power state.
+--- The `power` module contains properties and functions that relate to the
+--- device's battery and charging 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.

luals-stubs/queue.lua

@@ -1,15 +1,31 @@
 --- @meta
 
---- Properties and functions for inspecting and manipulating the track playback queue
+--- The `queue` module contains Properties and functions that relate to the
+--- device's playback queue. This is a persistent, disk-backed list of TrackIds
+--- that includes the currently playing track, tracks that have been played,
+--- and tracks that are scheduled to be played after the current track has
+--- finished.
 --- @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 repeat_track Property Whether or not the current track will repeat indefinitely. 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.
+--- @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 = {}
 
+--- Adds the given track or database iterator to the end of the queue. Database
+--- iterators passed to this method will be unnested and expanded into the track
+--- ids they contain.
+--- @param val TrackId|Iterator
+function queue.add(val) end
+
+--- Removes all tracks from the queue.
+function queue.clear() end
+
+--- Moves forward in the play queue, looping back around to the beginning if repeat is on.
 function queue.next() end
+
+--- Moves backward in the play queue, looping back around to the end if repeat is on.
 function queue.previous() end
 
 return queue

luals-stubs/screen.lua

@@ -0,0 +1,25 @@
+--- @meta
+
+--- A distinct full-screen UI. Each screen has an associated LVGL UI tree and
+--- group, and can be shown on-screen using the 'backstack' module.
+--- Screens make use of prototype inheritance in order to provide a consistent
+--- interface for the C++ firmware to work with.
+--- See [Programming in Lua, chapter 16](https://www.lua.org/pil/16.2.html).
+--- @class screen
+local screen = {}
+
+--- Creates a new screen instance.
+function screen:new(params) end
+
+--- Called just before this screen is first displayed to the user.
+function screen:createUi() end
+
+--- Called whenever this screen is displayed to the user.
+function screen:onShown() end
+
+--- Called whenever this screen is being hidden by the user; either because a
+--- new screen is being pushed on top of this way, or because this screen has
+--- been popped off of the stack.
+function screen:onHidden() end
+
+return screen

luals-stubs/time.lua

@@ -0,0 +1,12 @@
+--- @meta
+
+--- The `time` module contains functions for dealing with the current time
+--- since boot.
+--- @class time
+local time = {}
+
+--- Returns the time in milliseconds since the device booted.
+--- @return integer
+function time.ticks() end
+
+return time

luals-stubs/types.lua

@@ -1,13 +1,23 @@
 --- @meta
 
+--- A observable value, owned by the C++ firmware.
 ---@class Property
 local property = {}
 
+--- @return integer|string|table|boolean val Returns the property's current value
 function property:get() end
 
+--- Sets a new value. Not all properties may be set from within Lua code. For
+--- example, it makes little sense to attempt to override the current battery
+--- level.
+--- @param val? integer|string|table|boolean The new value. Optional; if not argument is passed, the property will be set to 'nil'.
+--- @return boolean success whether or not the new value was accepted
 function property:set(val) end
 
---- @param fn function
+--- Invokes the given function once immediately with the current value, and then again whenever the value changes.
+--- The function is invoked for *all* changes; both from the underlying C++ data, and from calls to `set` (if this is a Lua-writeable property).
+--- The binding will be active **only** so long as the given function remains in scope.
+--- @param fn function callback to apply property values. Must accept one argument; the updated value.
 function property:bind(fn) end
 
 return property

luals-stubs/volume.lua

@@ -1,8 +1,11 @@
 --- @meta
 
+--- 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.
 --- @class volume
---- @field current_pct Property
---- @field current_db Property
+--- @field current_pct Property The current volume as a percentage of the current volume limit.
+--- @field current_db Property The current volume in terms of decibels relative to line level (only applicable to headphone output)
+--- @field left_bias Property An additional modifier in decibels to apply to the left channel (only applicable to headphone output)
+--- @field limit_db Property The maximum allowed output volume, in terms of decibels relative to line level (only applicable to headphone output)
 local volume = {}
 
 return volume