Merge pull request #124 from brianhuster/dev

Dev

doc/livepreview.txt

@@ -48,7 +48,7 @@ Server class for live-preview.nvim To call this class, do >lua
       • {watch_dir}  (`fun(self: Server, func: function)`) Watch a directory
                      for changes and send a message "reload" to a WebSocket
                      client
-      • {start}      (`fun(self: Server, ip: string, port: number, func: function, client: uv_tcp_t)`)
+      • {start}      (`fun(self: Server, ip: string, port: number, func: function)`)
                      Start the server
       • {stop}       (`fun(self: Server)`) Stop the server
 
@@ -68,15 +68,14 @@ Server:routes({path})                     *livepreview.server.Server:routes()*
     Return: ~
         (`string`) path to the file
 
-                                           *livepreview.server.Server:start()*
-Server:start({ip}, {port}, {func}, {client})
+Server:start({ip}, {port}, {func})         *livepreview.server.Server:start()*
     Start the server
 
     Parameters: ~
-      • {ip}      (`string`) IP address to bind to
-      • {port}    (`number`) port to bind to
-      • {func}    (`function`)
-      • {client}  (`uv_tcp_t`) uv_tcp client
+      • {ip}    (`string`) IP address to bind to
+      • {port}  (`number`) port to bind to
+      • {func}  (`function`)
+                • client uv_tcp_t: The uv_tcp client passed to func
 
 Server:stop()                               *livepreview.server.Server:stop()*
     Stop the server

lua/livepreview/server/Server.lua

@@ -95,8 +95,8 @@ end
 --- Start the server
 --- @param ip string: IP address to bind to
 --- @param port number: port to bind to
---- @param func function(client)|nil: function to call when when there is a change in the watched directory
---- 	@param client uv_tcp_t: uv_tcp client
+--- @param func function({client: uv_tcp_t})|nil # Function to call when there is a change in the watched directory
+--- 	- client uv_tcp_t: The uv_tcp client passed to func
 function Server:start(ip, port, func)
 	self.server:bind(ip, port)
 	self.server:listen(128, function(err)

scripts/gen_api_spec.lua

@@ -12,7 +12,7 @@ local function extract_functions(input)
 	for line in input:gmatch("[^\n]+") do
 		local func_name = line:match("/%*(%S+%b())%*")
 		if func_name then
-			func_name = func_name:gsub("live%-preview", "L")
+			func_name = func_name:gsub("livepreview", "L")
 			table.insert(functions, func_name)
 		end
 	end

scripts/gen_vimdoc.lua

@@ -1,29 +1,61 @@
--- Copyright Neovim contributors.
---
--- Licensed under the Apache License, Version 2.0 (the "License");
--- you may not use this file except in compliance with the License.
--- You may obtain a copy of the License at
---
---     http://www.apache.org/licenses/LICENSE-2.0
---
--- Unless required by applicable law or agreed to in writing, software
--- distributed under the License is distributed on an "AS IS" BASIS,
--- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
--- See the License for the specific language governing permissions and
--- limitations under the License.
---
+#!/usr/bin/env -S nvim -l
+--- Generates Nvim :help docs from Lua/C docstrings
+---
+--- The generated :help text for each function is formatted as follows:
+--- - Max width of 78 columns (`TEXT_WIDTH`).
+--- - Indent with spaces (not tabs).
+--- - Indent of 4 columns for body text (`INDENTATION`).
+--- - Function signature and helptag (right-aligned) on the same line.
+---   - Signature and helptag must have a minimum of 8 spaces between them.
+---   - If the signature is too long, it is placed on the line after the helptag.
+---     Signature wraps with subsequent lines indented to the open parenthesis.
+---   - Subsection bodies are indented an additional 4 spaces.
+--- - Body consists of function description, parameters, return description, and
+---   C declaration (`INCLUDE_C_DECL`).
+--- - Parameters are omitted for the `void` and `Error *` types, or if the
+---   parameter is marked as [out].
+--- - Each function documentation is separated by a single line.
 
 local luacats_parser = require('scripts.luacats_parser')
-local text_utils = require('scripts.text_utils')
+local util = require('scripts.text_utils')
 
 local fmt = string.format
 
-local wrap = text_utils.wrap
-local md_to_vimdoc = text_utils.md_to_vimdoc
+local wrap = util.wrap
+local md_to_vimdoc = util.md_to_vimdoc
 
 local TEXT_WIDTH = 78
 local INDENTATION = 4
 
+--- @class (exact) nvim.gen_vimdoc.Config
+---
+--- Generated documentation target, e.g. api.txt
+--- @field filename string
+---
+--- @field section_order string[]
+---
+--- List of files/directories for doxygen to read, relative to `base_dir`.
+--- @field files string[]
+---
+--- @field exclude_types? true
+---
+--- Section name overrides. Key: filename (e.g., vim.c)
+--- @field section_name? table<string,string>
+---
+--- @field fn_name_pat? string
+---
+--- @field fn_xform? fun(fun: nvim.luacats.parser.fun)
+---
+--- For generated section names.
+--- @field section_fmt fun(name: string): string
+---
+--- @field helptag_fmt fun(name: string): string|string[]
+---
+--- Per-function helptag.
+--- @field fn_helptag_fmt? fun(fun: nvim.luacats.parser.fun): string
+---
+--- @field append_only? string[]
+
 local function contains(t, xs)
 	return vim.tbl_contains(xs, t)
 end
@@ -72,6 +104,7 @@ local function fn_helptag_fmt_common(fun)
 	return fun.name .. fn_sfx
 end
 
+--- @type table<string,nvim.gen_vimdoc.Config>
 local config = {
 	lua = {
 		filename = 'livepreview.txt',
@@ -126,6 +159,7 @@ local config = {
 	}
 }
 
+
 --- @param ty string
 --- @param generics table<string,string>
 --- @return string
@@ -466,19 +500,25 @@ local function render_fun(fun, classes, cfg)
 	table.insert(ret, render_fun_header(fun, cfg))
 	table.insert(ret, '\n')
 
-	if fun.desc then
-		table.insert(ret, md_to_vimdoc(fun.desc, INDENTATION, INDENTATION, TEXT_WIDTH))
-	end
-
 	if fun.since then
-		local since = tonumber(fun.since)
+		local since = assert(tonumber(fun.since), 'invalid @since on ' .. fun.name)
 		local info = nvim_api_info()
-		if since and (since > info.level or since == info.level and info.prerelease) then
-			fun.notes = fun.notes or {}
-			table.insert(fun.notes, { desc = 'This API is pre-release (unstable).' })
+		if since == 0 or (info.prerelease and since == info.level) then
+			-- Experimental = (since==0 or current prerelease)
+			local s = 'WARNING: This feature is experimental/unstable.'
+			table.insert(ret, md_to_vimdoc(s, INDENTATION, INDENTATION, TEXT_WIDTH))
+			table.insert(ret, '\n')
+		else
+			local v = assert(util.version_level[since], 'invalid @since on ' .. fun.name)
+			fun.attrs = fun.attrs or {}
+			table.insert(fun.attrs, ('Since: %s'):format(v))
 		end
 	end
 
+	if fun.desc then
+		table.insert(ret, md_to_vimdoc(fun.desc, INDENTATION, INDENTATION, TEXT_WIDTH))
+	end
+
 	if fun.notes then
 		table.insert(ret, '\n    Note: ~\n')
 		for _, p in ipairs(fun.notes) do
@@ -557,7 +597,14 @@ local function render_funs(funs, classes, cfg)
 	return table.concat(ret)
 end
 
-local base_dir = vim.uv.cwd()
+--- @return string
+local function get_script_path()
+	local str = debug.getinfo(2, 'S').source:sub(2)
+	return str:match('(.*[/\\])') or './'
+end
+
+local script_path = get_script_path()
+local base_dir = vim.fs.dirname(vim.fs.dirname(script_path))
 
 local function delete_lines_below(doc_file, tokenstr)
 	local lines = {} --- @type string[]
@@ -609,7 +656,11 @@ local function make_section(filename, cfg, section_docs, funs_txt)
 	local sectname = cfg.section_name and cfg.section_name[filename] or mktitle(name)
 
 	-- section tag: e.g., "*api-autocmd*"
-	local help_tag = '*' .. cfg.helptag_fmt(sectname) .. '*'
+	local help_labels = cfg.helptag_fmt(sectname)
+	if type(help_labels) == 'table' then
+		help_labels = table.concat(help_labels, '* *')
+	end
+	local help_tags = '*' .. help_labels .. '*'
 
 	if funs_txt == '' and #section_docs == 0 then
 		return
@@ -618,7 +669,7 @@ local function make_section(filename, cfg, section_docs, funs_txt)
 	return {
 		name = sectname,
 		title = cfg.section_fmt(sectname),
-		help_tag = help_tag,
+		help_tag = help_tags,
 		funs_txt = funs_txt,
 		doc = section_docs,
 	}

scripts/luacats_grammar.lua

@@ -14,9 +14,6 @@
 --
 
 
---[[!
-LPEG grammar for LuaCATS
-]]
 --[[!
 LPEG grammar for LuaCATS
 ]]

tests/api_spec.lua

@@ -1,5 +1,5 @@
-L = require("live-preview")
-local functions = { "L.health.check()", "L.health.is_compatible()", "L.preview_file()", "L.server.Server:new()", "L.server.Server:routes()", "L.server.Server:start()", "L.server.Server:stop()", "L.server.Server:watch_dir()", "L.server.handler.client()", "L.server.handler.request()", "L.server.handler.send_http_response()", "L.server.handler.serve_file()", "L.server.utils.content_type.get()", "L.server.utils.etag.generate()", "L.server.websocket.handshake()", "L.server.websocket.send()", "L.setup()", "L.stop_preview()", "L.utils.await_term_cmd()", "L.utils.get_path_lua_file()", "L.utils.get_plugin_path()", "L.utils.kill_port()", "L.utils.open_browser()", "L.utils.sha1()", "L.utils.supported_filetype()", "L.utils.term_cmd()", "L.utils.uv_read_file()", "L.utils.uv_write_file()" }
+L = require("livepreview")
+local functions = { "L.health.check()", "L.health.is_compatible()", "L.preview_file()", "L.server.Server:new()", "L.server.Server:routes()", "L.server.Server:start()", "L.server.Server:stop()", "L.server.Server:watch_dir()", "L.server.handler.client()", "L.server.handler.request()", "L.server.handler.send_http_response()", "L.server.handler.serve_file()", "L.server.utils.content_type.get()", "L.server.utils.etag.generate()", "L.server.websocket.handshake()", "L.server.websocket.send()", "L.server.websocket.send_json()", "L.setup()", "L.stop_preview()", "L.utils.await_term_cmd()", "L.utils.get_path_lua_file()", "L.utils.get_plugin_path()", "L.utils.kill_port()", "L.utils.open_browser()", "L.utils.sha1()", "L.utils.supported_filetype()", "L.utils.term_cmd()", "L.utils.uv_read_file()", "L.utils.uv_write_file()" }
 describe("Testing API functions", function()
 	for _, func in ipairs(functions) do
 		it("should be accessible " .. func, function()