ci(lint): check `@brief` docstring placement #3762

17 files changed, 89 insertions, 66 deletions

diff --git a/.github/ci/lint.sh b/.github/ci/lint.sh
index 38ea57eb..ccd23b5b 100644
--- a/.github/ci/lint.sh
+++ b/.github/ci/lint.sh
@@ -17,6 +17,15 @@ _check_cmd_buflocal() {
   fi
 }
 
+# Check that "@brief" docstring is the first line of each "lsp/*.lua" config.
+_check_brief_placement() {
+  if find ./lsp -type f -name "*.lua" -exec awk 'NR==1 && !/brief/{print FILENAME}' {} \; | grep --color=never '.' ; then
+    echo
+    echo '`@brief` docstring must be at the top of the config source file'
+    exit 1
+  fi
+}
+
 # Enforce "Lsp" prefix on all user commands.
 _check_lsp_cmd_prefix() {
   local exclude='tinymist'
@@ -58,6 +67,7 @@ _check_deprecated_utils() {
 }
 
 _check_cmd_buflocal
+_check_brief_placement
 _check_lsp_cmd_prefix
 _check_exec_cmd
 _check_deprecated_utils
diff --git a/lsp/ada_ls.lua b/lsp/ada_ls.lua
index c3a05e32..ff43d9a0 100644
--- a/lsp/ada_ls.lua
+++ b/lsp/ada_ls.lua
@@ -1,5 +1,3 @@
-local util = require 'lspconfig.util'
-
 ---@brief
 ---
 --- https://github.com/AdaCore/ada_language_server
@@ -19,6 +17,9 @@ local util = require 'lspconfig.util'
 ---     }
 --- })
 --- ```
+
+local util = require 'lspconfig.util'
+
 return {
   cmd = { 'ada_language_server' },
   filetypes = { 'ada' },
diff --git a/lsp/agda_ls.lua b/lsp/agda_ls.lua
index 127b3081..b10f14e2 100644
--- a/lsp/agda_ls.lua
+++ b/lsp/agda_ls.lua
@@ -1,10 +1,11 @@
-local util = require 'lspconfig.util'
-
 ---@brief
 ---
 --- https://github.com/agda/agda-language-server
 ---
 --- Language Server for Agda.
+
+local util = require 'lspconfig.util'
+
 return {
   cmd = { 'als' },
   filetypes = { 'agda' },
diff --git a/lsp/angularls.lua b/lsp/angularls.lua
index dfb225aa..cdf28c9e 100644
--- a/lsp/angularls.lua
+++ b/lsp/angularls.lua
@@ -1,3 +1,22 @@
+---@brief
+---
+--- https://github.com/angular/vscode-ng-language-service
+--- `angular-language-server` can be installed via npm `npm install -g @angular/language-server`.
+---
+--- Note, that if you override the default `cmd`, you must also update `on_new_config` to set `new_config.cmd` during startup.
+---
+--- ```lua
+--- local project_library_path = "/path/to/project/lib"
+--- local cmd = {"ngserver", "--stdio", "--tsProbeLocations", project_library_path , "--ngProbeLocations", project_library_path}
+---
+--- require'lspconfig'.angularls.setup{
+---   cmd = cmd,
+---   on_new_config = function(new_config,new_root_dir)
+---     new_config.cmd = cmd
+---   end,
+--- }
+--- ```
+
 -- Angular requires a node_modules directory to probe for @angular/language-service and typescript
 -- in order to use your projects configured versions.
 local root_dir = vim.fn.getcwd()
@@ -54,25 +73,6 @@ local ng_probe_dirs = vim
   end)
   :join(',')
 
----@brief
----
---- https://github.com/angular/vscode-ng-language-service
---- `angular-language-server` can be installed via npm `npm install -g @angular/language-server`.
----
---- Note, that if you override the default `cmd`, you must also update `on_new_config` to set `new_config.cmd` during startup.
----
---- ```lua
---- local project_library_path = "/path/to/project/lib"
---- local cmd = {"ngserver", "--stdio", "--tsProbeLocations", project_library_path , "--ngProbeLocations", project_library_path}
----
---- require'lspconfig'.angularls.setup{
----   cmd = cmd,
----   on_new_config = function(new_config,new_root_dir)
----     new_config.cmd = cmd
----   end,
---- }
---- ```
-
 return {
   cmd = {
     'ngserver',
diff --git a/lsp/arduino_language_server.lua b/lsp/arduino_language_server.lua
index 588dec0f..0b47a700 100644
--- a/lsp/arduino_language_server.lua
+++ b/lsp/arduino_language_server.lua
@@ -1,5 +1,3 @@
-local util = require 'lspconfig.util'
-
 ---@brief
 ---
 --- https://github.com/arduino/arduino-language-server
@@ -69,6 +67,9 @@ local util = require 'lspconfig.util'
 ---
 --- Note that an upstream bug makes keywords in some cases become undefined by the language server.
 --- Ref: https://github.com/arduino/arduino-ide/issues/159
+
+local util = require 'lspconfig.util'
+
 return {
   filetypes = { 'arduino' },
   root_dir = function(bufnr, on_dir)
diff --git a/lsp/astro.lua b/lsp/astro.lua
index 86f834fa..2bd64310 100644
--- a/lsp/astro.lua
+++ b/lsp/astro.lua
@@ -1,8 +1,3 @@
-local function get_typescript_server_path(root_dir)
-  local project_root = vim.fs.dirname(vim.fs.find('node_modules', { path = root_dir, upward = true })[1])
-  return project_root and vim.fs.joinpath(project_root, 'node_modules', 'typescript', 'lib') or ''
-end
-
 ---@brief
 ---
 --- https://github.com/withastro/language-tools/tree/main/packages/language-server
@@ -12,6 +7,11 @@ end
 --- npm install -g @astrojs/language-server
 --- ```
 
+local function get_typescript_server_path(root_dir)
+  local project_root = vim.fs.dirname(vim.fs.find('node_modules', { path = root_dir, upward = true })[1])
+  return project_root and vim.fs.joinpath(project_root, 'node_modules', 'typescript', 'lib') or ''
+end
+
 return {
   cmd = { 'astro-ls', '--stdio' },
   filetypes = { 'astro' },
diff --git a/lsp/autohotkey_lsp.lua b/lsp/autohotkey_lsp.lua
index 6f7a8624..eac26a7d 100644
--- a/lsp/autohotkey_lsp.lua
+++ b/lsp/autohotkey_lsp.lua
@@ -1,14 +1,16 @@
--- NOTE: AutoHotkey is used only on windows
-local function get_autohotkey_path()
-  local path = vim.fn.exepath('autohotkey.exe')
-  return #path > 0 and path or ''
-end
-
 ---@brief
 ---
 --- https://github.com/thqby/vscode-autohotkey2-lsp
 ---
 --- AutoHotkey v2.0 LSP implementation
+---
+--- NOTE: AutoHotkey is Windows-only.
+
+local function get_autohotkey_path()
+  local path = vim.fn.exepath('autohotkey.exe')
+  return #path > 0 and path or ''
+end
+
 return {
   cmd = { 'autohotkey_lsp', '--stdio' },
   filetypes = { 'autohotkey' },
diff --git a/lsp/autotools_ls.lua b/lsp/autotools_ls.lua
index 8777bfbb..caa17b29 100644
--- a/lsp/autotools_ls.lua
+++ b/lsp/autotools_ls.lua
@@ -1,7 +1,3 @@
-local util = require 'lspconfig.util'
-
-local root_files = { 'configure.ac', 'Makefile', 'Makefile.am', '*.mk' }
-
 ---@brief
 ---
 --- https://github.com/Freed-Wu/autotools-language-server
@@ -12,6 +8,11 @@ local root_files = { 'configure.ac', 'Makefile', 'Makefile.am', '*.mk' }
 --- ```
 ---
 --- Language server for autoconf, automake and make using tree sitter in python.
+
+local util = require 'lspconfig.util'
+
+local root_files = { 'configure.ac', 'Makefile', 'Makefile.am', '*.mk' }
+
 return {
   cmd = { 'autotools-language-server' },
   filetypes = { 'config', 'automake', 'make' },
diff --git a/lsp/awk_ls.lua b/lsp/awk_ls.lua
index 0bc1e6c7..1c609cdf 100644
--- a/lsp/awk_ls.lua
+++ b/lsp/awk_ls.lua
@@ -1,8 +1,3 @@
-if vim.version().major == 0 and vim.version().minor < 7 then
-  vim.notify('The AWK language server requires nvim >= 0.7', vim.log.levels.ERROR)
-  return
-end
-
 ---@brief
 ---
 --- https://github.com/Beaglefoot/awk-language-server/
@@ -11,6 +6,7 @@ end
 --- ```sh
 --- npm install -g awk-language-server
 --- ```
+
 return {
   cmd = { 'awk-language-server' },
   filetypes = { 'awk' },
diff --git a/lsp/buf_ls.lua b/lsp/buf_ls.lua
index f32a0a6c..16f5dc11 100644
--- a/lsp/buf_ls.lua
+++ b/lsp/buf_ls.lua
@@ -1,8 +1,10 @@
--- https://github.com/bufbuild/buf
---
--- buf beta lsp included in the cli itself
---
--- buf beta lsp is a Protobuf language server compatible with Buf modules and workspaces
+--- @brief
+--- https://github.com/bufbuild/buf
+---
+--- buf beta lsp included in the cli itself
+---
+--- buf beta lsp is a Protobuf language server compatible with Buf modules and workspaces
+
 return {
   cmd = { 'buf', 'beta', 'lsp', '--timeout=0', '--log-format=text' },
   filetypes = { 'proto' },
diff --git a/lsp/csharp_ls.lua b/lsp/csharp_ls.lua
index 58fde569..4e29c4bb 100644
--- a/lsp/csharp_ls.lua
+++ b/lsp/csharp_ls.lua
@@ -1,5 +1,3 @@
-local util = require 'lspconfig.util'
-
 ---@brief
 ---
 --- https://github.com/razzmatazz/csharp-language-server
@@ -9,6 +7,9 @@ local util = require 'lspconfig.util'
 --- csharp-ls requires the [dotnet-sdk](https://dotnet.microsoft.com/download) to be installed.
 ---
 --- The preferred way to install csharp-ls is with `dotnet tool install --global csharp-ls`.
+
+local util = require 'lspconfig.util'
+
 return {
   cmd = { 'csharp-ls' },
   root_dir = function(bufnr, on_dir)
diff --git a/lsp/daedalus_ls.lua b/lsp/daedalus_ls.lua
index e0a684f9..95da1eb7 100644
--- a/lsp/daedalus_ls.lua
+++ b/lsp/daedalus_ls.lua
@@ -1,3 +1,7 @@
+--- @brief
+---
+--- DaedalusLanguageServer
+
 return {
   cmd = { 'DaedalusLanguageServer' },
   filetypes = { 'd' },
diff --git a/lsp/foam_ls.lua b/lsp/foam_ls.lua
index 75f94265..c7a47f3c 100644
--- a/lsp/foam_ls.lua
+++ b/lsp/foam_ls.lua
@@ -1,5 +1,3 @@
-local util = require 'lspconfig.util'
-
 ---@brief
 ---
 --- https://github.com/FoamScience/foam-language-server
@@ -8,6 +6,9 @@ local util = require 'lspconfig.util'
 --- ```sh
 --- npm install -g foam-language-server
 --- ```
+
+local util = require 'lspconfig.util'
+
 return {
   cmd = { 'foam-ls', '--stdio' },
   filetypes = { 'foam', 'OpenFOAM' },
diff --git a/lsp/gdscript.lua b/lsp/gdscript.lua
index 22d379d4..79fe975a 100644
--- a/lsp/gdscript.lua
+++ b/lsp/gdscript.lua
@@ -1,11 +1,12 @@
-local port = os.getenv 'GDScript_Port' or '6005'
-local cmd = vim.lsp.rpc.connect('127.0.0.1', tonumber(port))
-
 ---@brief
 ---
 --- https://github.com/godotengine/godot
 ---
 --- Language server for GDScript, used by Godot Engine.
+
+local port = os.getenv 'GDScript_Port' or '6005'
+local cmd = vim.lsp.rpc.connect('127.0.0.1', tonumber(port))
+
 return {
   cmd = cmd,
   filetypes = { 'gd', 'gdscript', 'gdscript3' },
diff --git a/lsp/hls.lua b/lsp/hls.lua
index a9411f76..f6717e07 100644
--- a/lsp/hls.lua
+++ b/lsp/hls.lua
@@ -1,5 +1,3 @@
-local util = require 'lspconfig.util'
-
 ---@brief
 ---
 --- https://github.com/haskell/haskell-language-server
@@ -13,6 +11,9 @@ local util = require 'lspconfig.util'
 ---   filetypes = { 'haskell', 'lhaskell', 'cabal' },
 --- })
 --- ```
+
+local util = require 'lspconfig.util'
+
 return {
   cmd = { 'haskell-language-server-wrapper', '--lsp' },
   filetypes = { 'haskell', 'lhaskell' },
diff --git a/lsp/mdx_analyzer.lua b/lsp/mdx_analyzer.lua
index 36b84239..89413fd2 100644
--- a/lsp/mdx_analyzer.lua
+++ b/lsp/mdx_analyzer.lua
@@ -1,13 +1,13 @@
-local function get_typescript_server_path(root_dir)
-  local project_root = vim.fs.dirname(vim.fs.find('node_modules', { path = root_dir, upward = true })[1])
-  return project_root and vim.fs.joinpath(project_root, 'node_modules', 'typescript', 'lib') or ''
-end
-
 ---@brief
 ---https://github.com/mdx-js/mdx-analyzer
 ---
 ---`mdx-analyzer`, a language server for MDX
 
+local function get_typescript_server_path(root_dir)
+  local project_root = vim.fs.dirname(vim.fs.find('node_modules', { path = root_dir, upward = true })[1])
+  return project_root and vim.fs.joinpath(project_root, 'node_modules', 'typescript', 'lib') or ''
+end
+
 return {
   cmd = { 'mdx-language-server', '--stdio' },
   filetypes = { 'mdx' },
diff --git a/lsp/solc.lua b/lsp/solc.lua
index e7acbac5..0e03bab3 100644
--- a/lsp/solc.lua
+++ b/lsp/solc.lua
@@ -1,10 +1,11 @@
-local util = require 'lspconfig.util'
-
 ---@brief
 ---
 --- https://docs.soliditylang.org/en/latest/installing-solidity.html
 ---
 --- solc is the native language server for the Solidity language.
+
+local util = require 'lspconfig.util'
+
 return {
   cmd = { 'solc', '--lsp' },
   filetypes = { 'solidity' },