From 63de62cd0b0b53c5946d67ee2a3c2dac16379707 Mon Sep 17 00:00:00 2001
From: William Boman <william@redwill.se>
Date: Thu, 14 Jul 2022 17:27:12 +0200
Subject: [PATCH] chore: change emmylua annotation syntax from @ to : for
 comments (#73)

---
 lua/mason-core/async/init.lua             |  2 +-
 lua/mason-core/fetch.lua                  |  2 +-
 lua/mason-core/fs.lua                     |  4 +--
 lua/mason-core/functional/list.lua        |  2 +-
 lua/mason-core/installer/context.lua      | 30 +++++++++++------------
 lua/mason-core/installer/handle.lua       |  2 +-
 lua/mason-core/managers/cargo/client.lua  |  2 +-
 lua/mason-core/managers/cargo/init.lua    |  4 +--
 lua/mason-core/managers/composer/init.lua |  4 +--
 lua/mason-core/managers/gem/init.lua      |  4 +--
 lua/mason-core/managers/git/init.lua      |  2 +-
 lua/mason-core/managers/github/client.lua | 22 ++++++++---------
 lua/mason-core/managers/go/init.lua       |  6 ++---
 lua/mason-core/managers/luarocks/init.lua |  4 +--
 lua/mason-core/managers/npm/init.lua      |  8 +++---
 lua/mason-core/managers/opam/init.lua     |  4 +--
 lua/mason-core/managers/pip3/init.lua     |  4 +--
 lua/mason-core/managers/std/init.lua      |  4 +--
 lua/mason-core/optional.lua               |  2 +-
 lua/mason-core/package/init.lua           |  4 +--
 lua/mason-core/platform.lua               |  4 +--
 lua/mason-core/process.lua                |  8 +++---
 lua/mason-core/result.lua                 |  2 +-
 lua/mason-core/spawn.lua                  | 14 +++++------
 lua/mason-core/ui/display.lua             | 12 ++++-----
 lua/mason-core/ui/init.lua                | 12 ++++-----
 lua/mason-lspconfig/api/command.lua       |  2 +-
 lua/mason/ui/components/json-schema.lua   |  2 +-
 lua/mason/ui/instance.lua                 |  2 +-
 tests/helpers/lua/luassertx.lua           |  4 +--
 30 files changed, 89 insertions(+), 89 deletions(-)

diff --git a/lua/mason-core/async/init.lua b/lua/mason-core/async/init.lua
index cf1580a85..7805cade9 100644
--- a/lua/mason-core/async/init.lua
+++ b/lua/mason-core/async/init.lua
@@ -39,7 +39,7 @@ local function table_pack(...)
 end
 
 ---@param async_fn fun(...)
----@param should_reject_err boolean|nil @Whether the provided async_fn takes a callback with the signature `fun(err, result)`
+---@param should_reject_err boolean|nil: Whether the provided async_fn takes a callback with the signature `fun(err, result)`
 local function promisify(async_fn, should_reject_err)
     return function(...)
         local args = table_pack(...)
diff --git a/lua/mason-core/fetch.lua b/lua/mason-core/fetch.lua
index 168d0b990..f6b28ebda 100644
--- a/lua/mason-core/fetch.lua
+++ b/lua/mason-core/fetch.lua
@@ -17,7 +17,7 @@ local USER_AGENT = "mason.nvim (+https://github.com/williamboman/mason.nvim)"
 ---@alias FetchOpts {out_file: string, method: FetchMethod, headers: table<string, string>, data: string}
 
 ---@async
----@param url string @The url to fetch.
+---@param url string: The url to fetch.
 ---@param opts FetchOpts | nil
 local function fetch(url, opts)
     opts = opts or {}
diff --git a/lua/mason-core/fs.lua b/lua/mason-core/fs.lua
index a69b5de51..f11c83c51 100644
--- a/lua/mason-core/fs.lua
+++ b/lua/mason-core/fs.lua
@@ -86,7 +86,7 @@ local function make_module(uv)
 
     ---@param path string
     ---@param contents string
-    ---@param flags string|nil @Defaults to "w".
+    ---@param flags string|nil: Defaults to "w".
     function M.write_file(path, contents, flags)
         log.debug("fs: write_file", path)
         local fd = uv.fs_open(path, flags or "w", 438)
@@ -112,7 +112,7 @@ local function make_module(uv)
 
     ---@alias ReaddirEntry {name: string, type: string}
 
-    ---@param path string @The full path to the directory to read.
+    ---@param path string: The full path to the directory to read.
     ---@return ReaddirEntry[]
     function M.readdir(path)
         log.trace("fs: fs_opendir", path)
diff --git a/lua/mason-core/functional/list.lua b/lua/mason-core/functional/list.lua
index 14db386ed..c3aaecd87 100644
--- a/lua/mason-core/functional/list.lua
+++ b/lua/mason-core/functional/list.lua
@@ -88,7 +88,7 @@ end, 2)
 
 ---@generic T
 ---@param list T[]
----@return T[] @A shallow copy of the list.
+---@return T[]: A shallow copy of the list.
 _.list_copy = _.map(fun.identity)
 
 _.concat = fun.curryN(function(a, b)
diff --git a/lua/mason-core/installer/context.lua b/lua/mason-core/installer/context.lua
index 3e701d8e0..a3577cfa1 100644
--- a/lua/mason-core/installer/context.lua
+++ b/lua/mason-core/installer/context.lua
@@ -53,39 +53,39 @@ function ContextualFs.new(cwd)
 end
 
 ---@async
----@param rel_path string @The relative path from the current working directory to the file to append.
+---@param rel_path string: The relative path from the current working directory to the file to append.
 ---@param contents string
 function ContextualFs:append_file(rel_path, contents)
     return fs.async.append_file(path.concat { self.cwd:get(), rel_path }, contents)
 end
 
 ---@async
----@param rel_path string @The relative path from the current working directory to the file to write.
+---@param rel_path string: The relative path from the current working directory to the file to write.
 ---@param contents string
 function ContextualFs:write_file(rel_path, contents)
     return fs.async.write_file(path.concat { self.cwd:get(), rel_path }, contents)
 end
 
 ---@async
----@param rel_path string @The relative path from the current working directory.
+---@param rel_path string: The relative path from the current working directory.
 function ContextualFs:file_exists(rel_path)
     return fs.async.file_exists(path.concat { self.cwd:get(), rel_path })
 end
 
 ---@async
----@param rel_path string @The relative path from the current working directory.
+---@param rel_path string: The relative path from the current working directory.
 function ContextualFs:dir_exists(rel_path)
     return fs.async.dir_exists(path.concat { self.cwd:get(), rel_path })
 end
 
 ---@async
----@param rel_path string @The relative path from the current working directory.
+---@param rel_path string: The relative path from the current working directory.
 function ContextualFs:rmrf(rel_path)
     return fs.async.rmrf(path.concat { self.cwd:get(), rel_path })
 end
 
 ---@async
----@param rel_path string @The relative path from the current working directory.
+---@param rel_path string: The relative path from the current working directory.
 function ContextualFs:unlink(rel_path)
     return fs.async.unlink(path.concat { self.cwd:get(), rel_path })
 end
@@ -104,7 +104,7 @@ function ContextualFs:mkdir(dirpath)
 end
 
 ---@class CwdManager
----@field private install_prefix string @Defines the upper boundary for which paths are allowed as cwd.
+---@field private install_prefix string: Defines the upper boundary for which paths are allowed as cwd.
 ---@field private cwd string
 local CwdManager = {}
 CwdManager.__index = CwdManager
@@ -185,8 +185,8 @@ function InstallContext:promote_cwd()
     self.cwd:set(install_path)
 end
 
----@param rel_path string @The relative path from the current working directory to change cwd to. Will only restore to the initial cwd after execution of fn (if provided).
----@param fn async fun() @(optional) The function to run in the context of the given path.
+---@param rel_path string: The relative path from the current working directory to change cwd to. Will only restore to the initial cwd after execution of fn (if provided).
+---@param fn async (fun()): (optional) The function to run in the context of the given path.
 function InstallContext:chdir(rel_path, fn)
     local old_cwd = self.cwd:get()
     self.cwd:set(path.concat { old_cwd, rel_path })
@@ -200,8 +200,8 @@ function InstallContext:chdir(rel_path, fn)
     end
 end
 
----@param new_executable_rel_path string @Relative path to the executable file to create.
----@param script_rel_path string @Relative path to the Node.js script.
+---@param new_executable_rel_path string: Relative path to the executable file to create.
+---@param script_rel_path string: Relative path to the Node.js script.
 function InstallContext:write_node_exec_wrapper(new_executable_rel_path, script_rel_path)
     return self:write_shell_exec_wrapper(
         new_executable_rel_path,
@@ -212,7 +212,7 @@ function InstallContext:write_node_exec_wrapper(new_executable_rel_path, script_
     )
 end
 
----@param new_executable_rel_path string @Relative path to the executable file to create.
+---@param new_executable_rel_path string: Relative path to the executable file to create.
 ---@param target_executable_rel_path string
 function InstallContext:write_exec_wrapper(new_executable_rel_path, target_executable_rel_path)
     return self:write_shell_exec_wrapper(
@@ -224,9 +224,9 @@ function InstallContext:write_exec_wrapper(new_executable_rel_path, target_execu
     )
 end
 
----@param new_executable_rel_path string @Relative path to the executable file to create.
----@param command string @The shell command to run.
----@return string @The created executable filename.
+---@param new_executable_rel_path string: Relative path to the executable file to create.
+---@param command string: The shell command to run.
+---@return string: The created executable filename.
 function InstallContext:write_shell_exec_wrapper(new_executable_rel_path, command)
     return platform.when {
         unix = function()
diff --git a/lua/mason-core/installer/handle.lua b/lua/mason-core/installer/handle.lua
index f2e7aa1de..222c7ddf3 100644
--- a/lua/mason-core/installer/handle.lua
+++ b/lua/mason-core/installer/handle.lua
@@ -99,7 +99,7 @@ function InstallHandle:deregister_spawn_handle(luv_handle)
     return false
 end
 
----@return Optional @Optional<InstallHandleSpawnHandle>
+---@return Optional: Optional<InstallHandleSpawnHandle>
 function InstallHandle:peek_spawn_handle()
     return Optional.of_nilable(self.spawn_handles[#self.spawn_handles])
 end
diff --git a/lua/mason-core/managers/cargo/client.lua b/lua/mason-core/managers/cargo/client.lua
index 3df7550b4..ae04691d5 100644
--- a/lua/mason-core/managers/cargo/client.lua
+++ b/lua/mason-core/managers/cargo/client.lua
@@ -6,7 +6,7 @@ local M = {}
 
 ---@async
 ---@param crate string
----@return Result @of Crate
+---@return Result: of Crate
 function M.fetch_crate(crate)
     return fetch(("https://crates.io/api/v1/crates/%s"):format(crate)):map_catching(vim.json.decode)
 end
diff --git a/lua/mason-core/managers/cargo/init.lua b/lua/mason-core/managers/cargo/init.lua
index 5b87667cc..c2d4f41d0 100644
--- a/lua/mason-core/managers/cargo/init.lua
+++ b/lua/mason-core/managers/cargo/init.lua
@@ -76,8 +76,8 @@ function M.install(crate, opts)
     }
 end
 
----@param output string @The `cargo install --list` output.
----@return table<string, string> @Key is the crate name, value is its version.
+---@param output string: The `cargo install --list` output.
+---@return table<string, string>: Key is the crate name, value is its version.
 function M.parse_installed_crates(output)
     local installed_crates = {}
     for _, line in ipairs(vim.split(output, "\n")) do
diff --git a/lua/mason-core/managers/composer/init.lua b/lua/mason-core/managers/composer/init.lua
index 96ab5f142..31c792a9b 100644
--- a/lua/mason-core/managers/composer/init.lua
+++ b/lua/mason-core/managers/composer/init.lua
@@ -26,7 +26,7 @@ local function with_receipt(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil } @The composer packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[] | nil }: The composer packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.packages(packages)
     return function()
         return M.require(packages).with_receipt()
@@ -34,7 +34,7 @@ function M.packages(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil } @The composer packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[] | nil }: The composer packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.require(packages)
     local ctx = installer.context()
     local pkgs = _.list_copy(packages)
diff --git a/lua/mason-core/managers/gem/init.lua b/lua/mason-core/managers/gem/init.lua
index 11019985a..8b64d68a6 100644
--- a/lua/mason-core/managers/gem/init.lua
+++ b/lua/mason-core/managers/gem/init.lua
@@ -25,7 +25,7 @@ local function with_receipt(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil } @The Gem packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[] | nil }: The Gem packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.packages(packages)
     return function()
         return M.install(packages).with_receipt()
@@ -33,7 +33,7 @@ function M.packages(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil } @The Gem packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[] | nil }: The Gem packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.install(packages)
     local ctx = installer.context()
     local pkgs = _.list_copy(packages or {})
diff --git a/lua/mason-core/managers/git/init.lua b/lua/mason-core/managers/git/init.lua
index 432d18f40..c363cbe84 100644
--- a/lua/mason-core/managers/git/init.lua
+++ b/lua/mason-core/managers/git/init.lua
@@ -14,7 +14,7 @@ local function with_receipt(repo)
 end
 
 ---@async
----@param opts {[1]: string, recursive: boolean, version: Optional|nil} @The first item in the table is the repository to clone.
+---@param opts {[1]: string, recursive: boolean, version: Optional|nil}: The first item in the table is the repository to clone.
 function M.clone(opts)
     local ctx = installer.context()
     local repo = assert(opts[1], "No git URL provided.")
diff --git a/lua/mason-core/managers/github/client.lua b/lua/mason-core/managers/github/client.lua
index 1bcede7ae..b2ddb44d7 100644
--- a/lua/mason-core/managers/github/client.lua
+++ b/lua/mason-core/managers/github/client.lua
@@ -10,7 +10,7 @@ local M = {}
 ---@alias GitHubTag {name: string}
 
 ---@param path string
----@return Result @JSON decoded response.
+---@return Result: JSON decoded response.
 local function api_call(path)
     return spawn
         .gh({ "api", path })
@@ -22,8 +22,8 @@ local function api_call(path)
 end
 
 ---@async
----@param repo string @The GitHub repo ("username/repo").
----@return Result @of GitHubRelease[]
+---@param repo string: The GitHub repo ("username/repo").
+---@return Result: of GitHubRelease[]
 function M.fetch_releases(repo)
     log.fmt_trace("Fetching GitHub releases for repo=%s", repo)
     local path = ("repos/%s/releases"):format(repo)
@@ -33,8 +33,8 @@ function M.fetch_releases(repo)
 end
 
 ---@async
----@param repo string @The GitHub repo ("username/repo").
----@param tag_name string @The tag_name of the release to fetch.
+---@param repo string: The GitHub repo ("username/repo").
+---@param tag_name string: The tag_name of the release to fetch.
 function M.fetch_release(repo, tag_name)
     log.fmt_trace("Fetching GitHub release for repo=%s, tag_name=%s", repo, tag_name)
     local path = ("repos/%s/releases/tags/%s"):format(repo, tag_name)
@@ -59,9 +59,9 @@ end
 ---@alias FetchLatestGithubReleaseOpts {tag_name_pattern:string|nil, include_prerelease: boolean}
 
 ---@async
----@param repo string @The GitHub repo ("username/repo").
+---@param repo string: The GitHub repo ("username/repo").
 ---@param opts FetchLatestGithubReleaseOpts|nil
----@return Result @of GitHubRelease
+---@return Result: of GitHubRelease
 function M.fetch_latest_release(repo, opts)
     opts = opts or {
         tag_name_pattern = nil,
@@ -86,8 +86,8 @@ function M.fetch_latest_release(repo, opts)
 end
 
 ---@async
----@param repo string @The GitHub repo ("username/repo").
----@return Result @of GitHubTag[]
+---@param repo string: The GitHub repo ("username/repo").
+---@return Result: of GitHubTag[]
 function M.fetch_tags(repo)
     local path = ("repos/%s/tags"):format(repo)
     return api_call(path):map_err(function()
@@ -96,8 +96,8 @@ function M.fetch_tags(repo)
 end
 
 ---@async
----@param repo string @The GitHub repo ("username/repo").
----@return Result @Result<string> - The latest tag name.
+---@param repo string: The GitHub repo ("username/repo").
+---@return Result: Result<string> - The latest tag name.
 function M.fetch_latest_tag(repo)
     -- https://github.com/williamboman/vercel-github-api-latest-tag-proxy
     return fetch(("https://latest-github-tag.redwill.se/api/latest-tag?repo=%s"):format(repo))
diff --git a/lua/mason-core/managers/go/init.lua b/lua/mason-core/managers/go/init.lua
index dbdfdc455..9c9694093 100644
--- a/lua/mason-core/managers/go/init.lua
+++ b/lua/mason-core/managers/go/init.lua
@@ -24,7 +24,7 @@ local function with_receipt(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil } @The go packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[] | nil }: The go packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.packages(packages)
     return function()
         M.install(packages).with_receipt()
@@ -32,7 +32,7 @@ function M.packages(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil } @The go packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[] | nil }: The go packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.install(packages)
     local ctx = installer.context()
     local env = {
@@ -66,7 +66,7 @@ function M.install(packages)
     }
 end
 
----@param output string @The output from `go version -m` command.
+---@param output string: The output from `go version -m` command.
 function M.parse_mod_version_output(output)
     ---@type {path: string[], mod: string[], dep: string[], build: string[]}
     local result = {}
diff --git a/lua/mason-core/managers/luarocks/init.lua b/lua/mason-core/managers/luarocks/init.lua
index 7ec082c80..f98efb815 100644
--- a/lua/mason-core/managers/luarocks/init.lua
+++ b/lua/mason-core/managers/luarocks/init.lua
@@ -21,7 +21,7 @@ local function with_receipt(package)
     end
 end
 
----@param package string @The luarock package to install.
+---@param package string: The luarock package to install.
 ---@param opts { dev: boolean, bin : string[] | nil } | nil
 function M.package(package, opts)
     return function()
@@ -30,7 +30,7 @@ function M.package(package, opts)
 end
 
 ---@async
----@param pkg string @The luarock package to install.
+---@param pkg string: The luarock package to install.
 ---@param opts { dev: boolean, bin : string[] | nil } | nil
 function M.install(pkg, opts)
     opts = opts or {}
diff --git a/lua/mason-core/managers/npm/init.lua b/lua/mason-core/managers/npm/init.lua
index 828afd125..b3aa0f0b7 100644
--- a/lua/mason-core/managers/npm/init.lua
+++ b/lua/mason-core/managers/npm/init.lua
@@ -36,7 +36,7 @@ local function with_receipt(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil } @The npm packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[] | nil }: The npm packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.packages(packages)
     return function()
         return M.install(packages).with_receipt()
@@ -44,7 +44,7 @@ function M.packages(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil } @The npm packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[] | nil }: The npm packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.install(packages)
     local ctx = installer.context()
     local pkgs = list_copy(packages)
@@ -77,14 +77,14 @@ function M.install(packages)
 end
 
 ---@async
----@param exec_args string[] @The arguments to pass to npm exec.
+---@param exec_args string[]: The arguments to pass to npm exec.
 function M.exec(exec_args)
     local ctx = installer.context()
     ctx.spawn.npm { "exec", "--yes", "--", exec_args }
 end
 
 ---@async
----@param script string @The npm script to run.
+---@param script string: The npm script to run.
 function M.run(script)
     local ctx = installer.context()
     ctx.spawn.npm { "run", script }
diff --git a/lua/mason-core/managers/opam/init.lua b/lua/mason-core/managers/opam/init.lua
index 8b42e4e97..63654ea36 100644
--- a/lua/mason-core/managers/opam/init.lua
+++ b/lua/mason-core/managers/opam/init.lua
@@ -24,7 +24,7 @@ local function with_receipt(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil } @The opam packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[] | nil }: The opam packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.packages(packages)
     return function()
         return M.install(packages).with_receipt()
@@ -32,7 +32,7 @@ function M.packages(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil } @The opam packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[] | nil }: The opam packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.install(packages)
     local ctx = installer.context()
     local pkgs = list_copy(packages)
diff --git a/lua/mason-core/managers/pip3/init.lua b/lua/mason-core/managers/pip3/init.lua
index 9502e89eb..4464c22cc 100644
--- a/lua/mason-core/managers/pip3/init.lua
+++ b/lua/mason-core/managers/pip3/init.lua
@@ -28,7 +28,7 @@ local function with_receipt(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil } @The pip packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[] | nil }: The pip packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.packages(packages)
     return function()
         return M.install(packages).with_receipt()
@@ -36,7 +36,7 @@ function M.packages(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil } @The pip packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[] | nil }: The pip packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.install(packages)
     local ctx = installer.context()
     local pkgs = _.list_copy(packages)
diff --git a/lua/mason-core/managers/std/init.lua b/lua/mason-core/managers/std/init.lua
index e021a261a..a0f9ecc99 100644
--- a/lua/mason-core/managers/std/init.lua
+++ b/lua/mason-core/managers/std/init.lua
@@ -163,8 +163,8 @@ function M.gunzip(file)
 end
 
 ---@async
----@param flags string @The chmod flag to apply.
----@param files string[] @A list of relative paths to apply the chmod on.
+---@param flags string: The chmod flag to apply.
+---@param files string[]: A list of relative paths to apply the chmod on.
 function M.chmod(flags, files)
     if platform.is_unix then
         local ctx = installer.context()
diff --git a/lua/mason-core/optional.lua b/lua/mason-core/optional.lua
index 5710ce0cc..e2b2599f2 100644
--- a/lua/mason-core/optional.lua
+++ b/lua/mason-core/optional.lua
@@ -72,7 +72,7 @@ function Optional:or_(supplier)
     end
 end
 
----@param exception any @(optional) The exception to throw if the result is a failure.
+---@param exception any: (optional) The exception to throw if the result is a failure.
 function Optional:or_else_throw(exception)
     if self:is_present() then
         return self._value
diff --git a/lua/mason-core/package/init.lua b/lua/mason-core/package/init.lua
index 1627c1ec3..b7af84397 100644
--- a/lua/mason-core/package/init.lua
+++ b/lua/mason-core/package/init.lua
@@ -16,7 +16,7 @@ local version_checks = require "mason-core.package.version-check"
 ---@class Package : EventEmitter
 ---@field name string
 ---@field spec PackageSpec
----@field private handle InstallHandle @The currently associated handle.
+---@field private handle InstallHandle: The currently associated handle.
 local Package = setmetatable({}, { __index = EventEmitter })
 
 ---@param package_identifier string
@@ -168,7 +168,7 @@ function Package:get_install_path()
     return path.package_prefix(self.name)
 end
 
----@return Optional @Optional<@see InstallReceipt>
+---@return Optional: Optional<InstallReceipt>
 function Package:get_receipt()
     local receipt_path = path.concat { self:get_install_path(), "mason-receipt.json" }
     if fs.sync.file_exists(receipt_path) then
diff --git a/lua/mason-core/platform.lua b/lua/mason-core/platform.lua
index 987e70bff..8fc6ba38f 100644
--- a/lua/mason-core/platform.lua
+++ b/lua/mason-core/platform.lua
@@ -63,7 +63,7 @@ M.os_distribution = fun.lazy(function()
     local Result = require "mason-core.result"
 
     ---Parses the provided contents of an /etc/\*-release file and identifies the Linux distribution.
-    ---@param contents string @The contents of a /etc/\*-release file.
+    ---@param contents string: The contents of a /etc/\*-release file.
     ---@return table<string, any>
     local function parse_linux_dist(contents)
         local lines = vim.split(contents, "\n")
@@ -121,7 +121,7 @@ M.os_distribution = fun.lazy(function()
     }
 end)
 
----@type async fun() Result @of String
+---@type async fun(): Result<string>
 M.get_homebrew_prefix = fun.lazy(function()
     assert(M.is_mac, "Can only locate Homebrew installation on Mac systems.")
     local spawn = require "mason-core.spawn"
diff --git a/lua/mason-core/process.lua b/lua/mason-core/process.lua
index fd4eb94fa..0c72aa2bf 100644
--- a/lua/mason-core/process.lua
+++ b/lua/mason-core/process.lua
@@ -34,7 +34,7 @@ end
 -- Also, there's no particular reason we need to refresh the environment (yet).
 local initial_environ = vim.fn.environ()
 
----@param new_paths string[] @A list of paths to prepend the existing PATH with.
+---@param new_paths string[]: A list of paths to prepend the existing PATH with.
 function M.extend_path(new_paths)
     local new_path_str = table.concat(new_paths, platform.path_sep)
     return ("%s%s%s"):format(new_path_str, platform.path_sep, initial_environ.PATH or "")
@@ -87,15 +87,15 @@ end
 ---@alias JobSpawnCallback fun(success: boolean, exit_code: integer, signal: integer)
 
 ---@class JobSpawnOpts
----@field env string[] @List of "key=value" string.
+---@field env string[]: List of "key=value" string.
 ---@field args string[]
 ---@field cwd string
 ---@field stdio_sink StdioSink
 
----@param cmd string @The command/executable.
+---@param cmd string: The command/executable.
 ---@param opts JobSpawnOpts
 ---@param callback JobSpawnCallback
----@return luv_handle,luv_pipe[],integer @Returns the job handle and the stdio array on success, otherwise returns nil.
+---@return luv_handle,luv_pipe[],integer: Returns the job handle and the stdio array on success, otherwise returns nil.
 function M.spawn(cmd, opts, callback)
     local stdin = uv.new_pipe(false)
     local stdout = uv.new_pipe(false)
diff --git a/lua/mason-core/result.lua b/lua/mason-core/result.lua
index 132e27581..0a615b8f8 100644
--- a/lua/mason-core/result.lua
+++ b/lua/mason-core/result.lua
@@ -40,7 +40,7 @@ function Result:get_or_else(value)
     end
 end
 
----@param exception any @(optional) The exception to throw if the result is a failure.
+---@param exception any: (optional) The exception to throw if the result is a failure.
 function Result:get_or_throw(exception)
     if self:is_success() then
         return self.value
diff --git a/lua/mason-core/spawn.lua b/lua/mason-core/spawn.lua
index 6b7834924..305bbc12e 100644
--- a/lua/mason-core/spawn.lua
+++ b/lua/mason-core/spawn.lua
@@ -41,13 +41,13 @@ local is_executable = _.memoize(function(cmd)
 end, _.identity)
 
 ---@class SpawnArgs
----@field with_paths string[] @Optional. Paths to add to the PATH environment variable.
----@field env table<string, string> @Optional. Example { SOME_ENV = "value", SOME_OTHER_ENV = "some_value" }
----@field env_raw string[] @Optional. Example: { "SOME_ENV=value", "SOME_OTHER_ENV=some_value" }
----@field stdio_sink StdioSink @Optional. If provided, will be used to write to stdout and stderr.
----@field cwd string @Optional
----@field on_spawn fun(handle: luv_handle, stdio: luv_pipe[]) @Optional. Will be called when the process successfully spawns.
----@field check_executable boolean @Optional. Whether to check if the provided command is executable (defaults to true).
+---@field with_paths string[]: (optional) Paths to add to the PATH environment variable.
+---@field env table<string, string>: (optional) Example { SOME_ENV = "value", SOME_OTHER_ENV = "some_value" }
+---@field env_raw string[]: (optional) Example: { "SOME_ENV=value", "SOME_OTHER_ENV=some_value" }
+---@field stdio_sink StdioSink: (optional) If provided, will be used to write to stdout and stderr.
+---@field cwd string: (optional)
+---@field on_spawn (fun(handle: luv_handle, stdio: luv_pipe[])): (optional) Will be called when the process successfully spawns.
+---@field check_executable boolean: (optional) Whether to check if the provided command is executable (defaults to true).
 
 setmetatable(spawn, {
     ---@param normalized_cmd string
diff --git a/lua/mason-core/ui/display.lua b/lua/mason-core/ui/display.lua
index 473680794..7a61d7661 100644
--- a/lua/mason-core/ui/display.lua
+++ b/lua/mason-core/ui/display.lua
@@ -76,8 +76,8 @@ local function render_node(viewport_context, node, _render_context, _output)
     ---@field diagnostic {message: string, severity: integer, source: string|nil}
 
     ---@class RenderOutput
-    ---@field lines string[] @The buffer lines.
-    ---@field virt_texts string[][] @List of (text, highlight) tuples.
+    ---@field lines string[]: The buffer lines.
+    ---@field virt_texts string[][]: List of (text, highlight) tuples.
     ---@field highlights RenderHighlight[]
     ---@field keybinds RenderKeybind[]
     ---@field diagnostics RenderDiagnostic[]
@@ -168,7 +168,7 @@ M._render_node = render_node
 ---@alias WindowOpts {effects: table<string, fun()>, highlight_groups: table<string, table>, border: string|table}
 
 ---@param opts WindowOpenOpts
----@param sizes_only boolean @Whether to only return properties that control the window size.
+---@param sizes_only boolean: Whether to only return properties that control the window size.
 local function create_popup_window_opts(opts, sizes_only)
     local win_height = vim.o.lines - vim.o.cmdheight - 2 -- Add margin for status and buffer line
     local win_width = vim.o.columns
@@ -191,7 +191,7 @@ local function create_popup_window_opts(opts, sizes_only)
     return popup_layout
 end
 
----@param name string @Human readable identifier.
+---@param name string: Human readable identifier.
 ---@param filetype string
 function M.new_view_only_win(name, filetype)
     local namespace = vim.api.nvim_create_namespace(("installer_%s"):format(name))
@@ -491,12 +491,12 @@ function M.new_view_only_win(name, filetype)
             vim.api.nvim_del_augroup_by_id(window_mgmt_augroup)
             vim.api.nvim_del_augroup_by_id(autoclose_augroup)
         end),
-        ---@param pos number[] @(row, col) tuple
+        ---@param pos number[]: (row, col) tuple
         set_cursor = function(pos)
             assert(win_id ~= nil, "Window has not been opened, cannot set cursor.")
             return vim.api.nvim_win_set_cursor(win_id, pos)
         end,
-        ---@return number[] @(row, col) tuple
+        ---@return number[]: (row, col) tuple
         get_cursor = function()
             assert(win_id ~= nil, "Window has not been opened, cannot get cursor.")
             return vim.api.nvim_win_get_cursor(win_id)
diff --git a/lua/mason-core/ui/init.lua b/lua/mason-core/ui/init.lua
index 0b288b20f..eafbf6ed0 100644
--- a/lua/mason-core/ui/init.lua
+++ b/lua/mason-core/ui/init.lua
@@ -61,7 +61,7 @@ function M.CascadingStyleNode(styles, children)
     return node
 end
 
----@param virt_text string[][] @List of (text, highlight) tuples.
+---@param virt_text string[][]: List of (text, highlight) tuples.
 function M.VirtualTextNode(virt_text)
     ---@class VirtualTextNode
     local node = {
@@ -95,10 +95,10 @@ function M.When(condition, node, default_val)
     return default_val or M.Node {}
 end
 
----@param key string @The keymap to register to. Example: "<CR>".
----@param effect string @The effect to call when keymap is triggered by the user.
----@param payload any @The payload to pass to the effect handler when triggered.
----@param is_global boolean|nil @Whether to register the keybind to apply on all lines in the buffer.
+---@param key string: The keymap to register to. Example: "<CR>".
+---@param effect string: The effect to call when keymap is triggered by the user.
+---@param payload any: The payload to pass to the effect handler when triggered.
+---@param is_global boolean|nil: Whether to register the keybind to apply on all lines in the buffer.
 function M.Keybind(key, effect, payload, is_global)
     ---@class KeybindHandlerNode
     local node = {
@@ -115,7 +115,7 @@ function M.EmptyLine()
     return M.Text { "" }
 end
 
----@param rows string[][][] @A list of rows to include in the table. Each row consists of an array of (text, highlight) tuples (aka spans).
+---@param rows string[][][]: A list of rows to include in the table. Each row consists of an array of (text, highlight) tuples (aka spans).
 function M.Table(rows)
     local col_maxwidth = {}
     for i = 1, #rows do
diff --git a/lua/mason-lspconfig/api/command.lua b/lua/mason-lspconfig/api/command.lua
index bf907ca2f..814be0ed1 100644
--- a/lua/mason-lspconfig/api/command.lua
+++ b/lua/mason-lspconfig/api/command.lua
@@ -6,7 +6,7 @@ local _ = require "mason-core.functional"
 local M = {}
 
 ---@async
----@param user_args string[] @The arguments, as provided by the user.
+---@param user_args string[]: The arguments, as provided by the user.
 local function parse_packages_from_user_args(user_args)
     local Package = require "mason-core.package"
     local server_mapping = require "mason-lspconfig.mappings.server"
diff --git a/lua/mason/ui/components/json-schema.lua b/lua/mason/ui/components/json-schema.lua
index 6a8f5110e..d7e3a1705 100644
--- a/lua/mason/ui/components/json-schema.lua
+++ b/lua/mason/ui/components/json-schema.lua
@@ -42,7 +42,7 @@ end
 ---@param schema table
 ---@param key string|nil
 ---@param level number|nil
----@param key_width number|nil @The width the key should occupate in the UI to produce an even column.
+---@param key_width number|nil: The width the key should occupate in the UI to produce an even column.
 ---@param compound_key string|nil
 local function JsonSchema(pkg, schema_id, state, schema, key, level, key_width, compound_key)
     level = level or 0
diff --git a/lua/mason/ui/instance.lua b/lua/mason/ui/instance.lua
index 7a9b98fad..185f9fa60 100644
--- a/lua/mason/ui/instance.lua
+++ b/lua/mason/ui/instance.lua
@@ -137,7 +137,7 @@ local mutate_state, get_state = window.state(INITIAL_STATE)
 
 ---@param pkg Package
 ---@param group string
----@param tail boolean|nil @Whether to insert at the end.
+---@param tail boolean|nil: Whether to insert at the end.
 local function mutate_package_grouping(pkg, group, tail)
     mutate_state(function(state)
         remove(state.packages.installing, pkg)
diff --git a/tests/helpers/lua/luassertx.lua b/tests/helpers/lua/luassertx.lua
index 35f7353f3..55ea0d72c 100644
--- a/tests/helpers/lua/luassertx.lua
+++ b/tests/helpers/lua/luassertx.lua
@@ -3,9 +3,9 @@ local match = require "luassert.match"
 local a = require "mason-core.async"
 
 local function wait_for(_, arguments)
-    ---@type fun() @Function to execute until it does not error.
+    ---@type (fun()): Function to execute until it does not error.
     local assertions_fn = arguments[1]
-    ---@type number @Timeout in milliseconds. Defaults to 5000.
+    ---@type number: Timeout in milliseconds. Defaults to 5000.
     local timeout = arguments[2]
     timeout = timeout or 15000