From b95d433047d2c273db896b4998e96223b3d78e00 Mon Sep 17 00:00:00 2001
From: Miku AuahDark <lumi.hotaru@gmail.com>
Date: Fri, 4 Oct 2024 17:51:16 +0800
Subject: [PATCH] Some more LuaLS documentation.

---
 audio_manager.lua    | 28 +++++++++++++++++++++++++---
 color.lua            |  1 +
 fixmrt.lua           |  2 +-
 game/bgm.lua         | 16 ++++++++++++++++
 game/color_theme.lua |  6 +++++-
 game/live/lyrics.lua |  4 ++--
 game/md5.lua         |  8 +++-----
 game/srt.lua         |  2 +-
 type.lua             |  2 +-
 util.lua             |  9 +++++++++
 volume.lua           | 11 ++++++++---
 11 files changed, 72 insertions(+), 17 deletions(-)

diff --git a/audio_manager.lua b/audio_manager.lua
index de98168f..586648bb 100644
--- a/audio_manager.lua
+++ b/audio_manager.lua
@@ -28,6 +28,7 @@ local AudioManager = {
 }
 
 -- must be called before any audio is loaded or the behaviour is undefined
+---@param rate integer
 function AudioManager.setRenderFramerate(rate)
 	if rate > 0 then
 		local smpPerFrame = 48000/rate
@@ -120,8 +121,11 @@ function AudioManager.newAudio(path, kind)
 	end
 end
 
+---@param data love.SoundData|love.Decoder|love.Data|love.File
+---@param kind string
+---@return livesim2.AudioManager.Object
 function AudioManager.newAudioDirect(data, kind)
-	--kind = kind or "master"
+	---@class livesim2.AudioManager.Object
 	local obj = {
 		pos = 0,
 		size = 0,
@@ -129,19 +133,24 @@ function AudioManager.newAudioDirect(data, kind)
 		volumeKind = kind,
 		playing = false,
 		looping = false,
+		---@type love.SoundData|nil
 		soundData = nil,
 		soundDataPointer = nil,
+		---@type love.SoundData|nil
 		originalSoundData = nil,
+		---@type integer
 		channelCount = nil,
+		---@type love.Source
 		source = nil,
 	}
 	if AudioManager.renderRate > 0 then
 		-- render mode requires 48000Hz
-		if type(data) == "userdata" and not(data:typeOf("SoundData")) then
+		if Util.isLOVEType(data) and not Util.isLOVEType(data, "SoundData") then
 			local sdAsync = Async.syncLily(lily.newSoundData(data))
 			data = sdAsync:getValues() -- automatically sync
 		end
 
+		---@cast data love.SoundData
 		obj.channelCount = Util.getChannelCount(data)
 
 		-- check sample rate
@@ -169,7 +178,8 @@ function AudioManager.newAudioDirect(data, kind)
 		obj.soundDataPointer = ffi.cast("short*", data:getPointer())
 		return obj
 	else
-		if type(data) == "userdata" and data:typeOf("SoundData") then
+		if Util.isLOVEType(data, "SoundData") then
+			---@cast data love.SoundData
 			obj.soundData = data
 			obj.source = love.audio.newSource(data)
 		else
@@ -181,7 +191,9 @@ function AudioManager.newAudioDirect(data, kind)
 	end
 end
 
+---@param obj livesim2.AudioManager.Object
 function AudioManager.clone(obj)
+	---@class livesim2.AudioManager.Object
 	local x = {
 		pos = 0,
 		size = obj.size,
@@ -200,6 +212,7 @@ function AudioManager.clone(obj)
 	return x
 end
 
+---@param obj livesim2.AudioManager.Object
 function AudioManager.play(obj)
 	if AudioManager.renderRate > 0 then
 		if obj.playing then return end
@@ -210,6 +223,7 @@ function AudioManager.play(obj)
 	end
 end
 
+---@param obj livesim2.AudioManager.Object
 function AudioManager.pause(obj)
 	if AudioManager.renderRate > 0 then
 		if not(obj.playing) then return end
@@ -226,6 +240,7 @@ function AudioManager.pause(obj)
 	end
 end
 
+---@param obj livesim2.AudioManager.Object
 function AudioManager.stop(obj)
 	if AudioManager.renderRate > 0 then
 		AudioManager.pause(obj)
@@ -235,6 +250,7 @@ function AudioManager.stop(obj)
 	end
 end
 
+---@param obj livesim2.AudioManager.Object
 function AudioManager.isLooping(obj)
 	if AudioManager.renderRate > 0 then
 		return obj.looping
@@ -243,6 +259,7 @@ function AudioManager.isLooping(obj)
 	end
 end
 
+---@param obj livesim2.AudioManager.Object
 function AudioManager.setLooping(obj, loop)
 	if AudioManager.renderRate > 0 then
 		obj.looping = loop
@@ -251,6 +268,7 @@ function AudioManager.setLooping(obj, loop)
 	end
 end
 
+---@param obj livesim2.AudioManager.Object
 function AudioManager.isPlaying(obj)
 	if AudioManager.renderRate > 0 then
 		return obj.playing
@@ -259,6 +277,8 @@ function AudioManager.isPlaying(obj)
 	end
 end
 
+---@param obj livesim2.AudioManager.Object
+---@param vol number
 function AudioManager.setVolume(obj, vol)
 	vol = Volume.get(obj.volumeKind, vol)
 	if AudioManager.renderRate > 0 then
@@ -268,6 +288,8 @@ function AudioManager.setVolume(obj, vol)
 	end
 end
 
+---@param obj livesim2.AudioManager.Object
+---@param seconds number
 function AudioManager.seek(obj, seconds)
 	if AudioManager.renderRate > 0 then
 		obj.pos = 48000 * seconds
diff --git a/color.lua b/color.lua
index 6829b979..237a0058 100644
--- a/color.lua
+++ b/color.lua
@@ -32,6 +32,7 @@ local function hexCache(hexcode)
 	return v
 end
 
+---@class color:{[string]:number[]}
 local color = setmetatable({}, {
 	__index = function(color, var)
 		if var:find("hex", 1, true) == 1 then
diff --git a/fixmrt.lua b/fixmrt.lua
index 3ce13e8a..b6a16c05 100644
--- a/fixmrt.lua
+++ b/fixmrt.lua
@@ -2,7 +2,7 @@
 -- This script patches LOVE rendering pipeline to workaround MRT bandwidth problem in some GPU drivers.
 -- See: https://github.com/love2d/love/commit/1896f82f5d40d33a551f7c5fd9662db3b4ccdf31
 
-if love.getVersion() < 11 or love._version >= "11.3" then
+if love.getVersion() ~= 11 or love._version >= "11.3" then
 	-- LOVE pre-11.0 does not have this problem.
 	-- LOVE 11.3 already have this problem worked around.
 	return true
diff --git a/game/bgm.lua b/game/bgm.lua
index 5f72594b..94cc7579 100644
--- a/game/bgm.lua
+++ b/game/bgm.lua
@@ -8,13 +8,16 @@ local AudioManager = require("audio_manager")
 local Util = require("util")
 
 local BGM = {}
+---@class livesim2.BGM
 local BGMClass = Luaoop.class("livesim2.BGM")
 
+---@param sd love.SoundData|love.Decoder|love.Data|love.File
 function BGMClass:__construct(sd)
 	if not(sd:typeOf("SoundData")) then
 		sd = love.sound.newSoundData(sd)
 	end
 
+	---@cast sd love.SoundData
 	self.audio = AudioManager.newAudioDirect(sd, "music")
 	self.channel = Util.getChannelCount(sd)
 	self.soundData = sd
@@ -33,11 +36,17 @@ function BGMClass:rewind()
 	return AudioManager.play(self.audio)
 end
 
+---@param sd love.SoundData
+---@param pos integer
 function BGMClass._getSampleSafe(sd, pos)
 	local s, v = pcall(sd.getSample, sd, pos)
 	return s and v or 0
 end
 
+---@param output number[]
+---@param sd love.SoundData
+---@param pos integer
+---@param amount integer
 function BGMClass:_populateSample(output, sd, pos, amount)
 	if self.channel == 1 then
 		-- mono
@@ -55,6 +64,8 @@ function BGMClass:_populateSample(output, sd, pos, amount)
 	end
 end
 
+---@param output number[]
+---@param amount integer
 function BGMClass:_getSamplesRender(output, amount)
 	-- Use original sound data
 	local sd, pos
@@ -71,6 +82,8 @@ function BGMClass:_getSamplesRender(output, amount)
 end
 
 -- interleaved samples: {l, r, l, r, l, r, ...}
+---@param amount integer
+---@return number[]
 function BGMClass:getSamples(amount)
 	local output = {}
 	if AudioManager.renderRate > 0 then
@@ -82,6 +95,7 @@ function BGMClass:getSamples(amount)
 	return output
 end
 
+---@param timepos number
 function BGMClass:seek(timepos)
 	return AudioManager.seek(self.audio, timepos)
 end
@@ -106,6 +120,8 @@ function BGMClass:getSampleRate()
 	end
 end
 
+---@param decoder love.FileData|love.File|string
+---@return livesim2.BGM
 function BGM.newSong(decoder)
 	return BGMClass(Util.newDecoder(decoder))
 end
diff --git a/game/color_theme.lua b/game/color_theme.lua
index 71fbda1a..2a9de230 100644
--- a/game/color_theme.lua
+++ b/game/color_theme.lua
@@ -66,11 +66,13 @@ local currentColor, currentColorDark, currentColorDarker
 
 -- colid: 1 = μ's, 2 = Aqours, 3 = NijiGaku, 4 = Liella, 5 = Hasunosora
 -- 6 = Musical, 7 = Yohane
+---@param colid integer
 function ColorTheme.init(colid)
 	if currentColor then return end
 	return ColorTheme.set(colid)
 end
 
+---@param colid integer
 function ColorTheme.set(colid)
 	if ColorTheme[colid] == nil then
 		error("unknown color id "..colid)
@@ -81,6 +83,7 @@ function ColorTheme.set(colid)
 	currentColorDarker = ColorTheme[colid].currentColorDarker
 end
 
+---@param opacity number
 function ColorTheme.get(opacity)
 	assert(currentColor, "forgot to call colorTheme.init()")
 	if opacity then
@@ -90,6 +93,7 @@ function ColorTheme.get(opacity)
 	end
 end
 
+---@param opacity number
 function ColorTheme.getDark(opacity)
 	assert(currentColorDark, "forgot to call colorTheme.init()")
 	if opacity then
@@ -99,7 +103,7 @@ function ColorTheme.getDark(opacity)
 	end
 end
 
-
+---@param opacity number
 function ColorTheme.getDarker(opacity)
 	assert(currentColorDarker, "forgot to call colorTheme.init()")
 	if opacity then
diff --git a/game/live/lyrics.lua b/game/live/lyrics.lua
index a15e1826..7de9ffd8 100644
--- a/game/live/lyrics.lua
+++ b/game/live/lyrics.lua
@@ -12,7 +12,7 @@ local MainFont = require("main_font")
 local Lyrics = Luaoop.class("Livesim2.Lyrics")
 local perZeroThree = 1/0.3
 
----@param srt Livesim2.SrtParseData[]
+---@param srt livesim2.SrtParseData[]
 function Lyrics:__construct(srt)
 	local font1, font2 = MainFont.get(24, 16)
 	local timings = {}
@@ -79,5 +79,5 @@ function Lyrics:draw()
 	end
 end
 
----@cast Lyrics +fun(srt:Livesim2.SrtParseData[]):Livesim2.Lyrics
+---@cast Lyrics +fun(srt:livesim2.SrtParseData[]):Livesim2.Lyrics
 return Lyrics
diff --git a/game/md5.lua b/game/md5.lua
index cb175887..4f11f65c 100644
--- a/game/md5.lua
+++ b/game/md5.lua
@@ -10,10 +10,6 @@ local Util = require("util")
 local md5impl
 local md5implfb
 
-local function isData(t)
-	return type(t) == "userdata" and t:typeOf("Data")
-end
-
 function md5implfb(code)
 	if type(code) == "userdata" and code:typeOf("Data") then
 		return md5fb.sum(code:getString())
@@ -29,8 +25,10 @@ if Util.compareLOVEVersion(11, 0) >= 0 then
 	end
 end
 
+---@param code string
+---@return string
 return function(code)
-	local len = isData(code) and code:getSize() or #code
+	local len = Util.isLOVEType(code, "Data") and code:getSize() or #code
 	-- https://bitbucket.org/rude/love/issues/1453
 	-- https://bitbucket.org/rude/love/pull-requests/117
 	-- LOVE 11.2 and earlier produces wrong hash for
diff --git a/game/srt.lua b/game/srt.lua
index 409be048..205d670b 100644
--- a/game/srt.lua
+++ b/game/srt.lua
@@ -8,7 +8,7 @@ end
 
 ---@param iter fun():(string|nil)
 return function(iter)
-	---@type Livesim2.SrtParseData[]
+	---@type livesim2.SrtParseData[]
 	local res = {}
 
 	-- ignore sub number, unnecessary
diff --git a/type.lua b/type.lua
index 42b4f780..1d5d245b 100644
--- a/type.lua
+++ b/type.lua
@@ -36,7 +36,7 @@ end
 ---@field public star integer
 local SummaryInfo = {}
 
----@class Livesim2.SrtParseData
+---@class livesim2.SrtParseData
 ---@field public start number
 ---@field public stop number
 ---@field public text1 string
diff --git a/util.lua b/util.lua
index ec3ff5c2..05a21927 100644
--- a/util.lua
+++ b/util.lua
@@ -126,6 +126,7 @@ function Util.releaseObject(obj)
 end
 
 ---@param sounddata love.SoundData
+---@return integer
 function Util.getChannelCount(sounddata)
 	if version11 then return sounddata:getChannelCount()
 	else return sounddata:getChannels() end
@@ -277,6 +278,8 @@ function Util.isMobile()
 	return love._os == "iOS" or love._os == "Android"
 end
 
+---@param path love.FileData|love.File|string
+---@return love.Decoder
 function Util.newDecoder(path)
 	if hasLVEP then
 		local s, v = pcall(love.sound.newDecoder, path)
@@ -538,6 +541,12 @@ function Util.split(text, delim, removeempty)
 	return t
 end
 
+---@param obj any
+---@param lovetype string?
+---@return boolean
+function Util.isLOVEType(obj, lovetype)
+	return type(obj) == "userdata" and obj.typeOf and obj:typeOf(lovetype or "Object")
+end
 
 if version11 then
 	local fontDPIScale = 1
diff --git a/volume.lua b/volume.lua
index a794fb51..88babad0 100644
--- a/volume.lua
+++ b/volume.lua
@@ -6,13 +6,16 @@ local Volume = {
 	list = {master = 0.8}
 }
 
--- volume default initialized to 0.8
+---@param name string
+---@param value number
 function Volume.define(name, value)
 	assert(Volume.list[name] == nil, "name already defined")
 	Volume.list[name] = assert(tonumber(value), "invalid default volume")
 end
 
--- value default to 1 if not specified
+---value default to 1 if not specified
+---@param name string
+---@param value number?
 function Volume.get(name, value)
 	assert(Volume.list[name], "name doesn't exist")
 	value = value or 1
@@ -23,7 +26,9 @@ function Volume.get(name, value)
 	end
 end
 
--- usually settings set the volume
+---usually settings set the volume
+---@param name string
+---@param value number
 function Volume.set(name, value)
 	Volume.list[name] = assert(tonumber(value), "invalid volume")
 end