Skip to content

Commit

Permalink
chore: formatting
Browse files Browse the repository at this point in the history
  • Loading branch information
@lewis6991
lewis6991 committed Jul 10, 2023
1 parent fd4d953 commit b7f6c52
Show file tree
Hide file tree
Showing 2 changed files with 68 additions and 58 deletions.
1 change: 1 addition & 0 deletions etc/doc_template.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ FUNCTIONS *gitsigns-functions*
Note functions with the {async} attribute are run asynchronously and are
non-blocking (return immediately).


{{FUNCTIONS}}

==============================================================================
Expand Down
125 changes: 67 additions & 58 deletions gen_help.lua
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ local config = require('lua.gitsigns.config')
--- @return string
local function read_file(path)
local f = assert(io.open(path, 'r'))
local t = f:read("*all")
local t = f:read('*all')
f:close()
return t
end
Expand All @@ -27,7 +27,7 @@ end
local function get_ordered_schema_keys()
local c = read_file('lua/gitsigns/config.lua')

local ci = c:gmatch("[^\n\r]+")
local ci = c:gmatch('[^\n\r]+')

for l in ci do
if startswith(l, 'M.schema = {') then
Expand All @@ -49,6 +49,8 @@ local function get_ordered_schema_keys()
return keys
end

--- @param dep_info boolean|{new_field: string, message: string, hard: boolean}
--- @param out fun(_: string?)
local function gen_config_doc_deprecated(dep_info, out)
if type(dep_info) == 'table' and dep_info.hard then
out(' HARD-DEPRECATED')
Expand All @@ -57,13 +59,15 @@ local function gen_config_doc_deprecated(dep_info, out)
end
if type(dep_info) == 'table' then
if dep_info.message then
out(' '..dep_info.message)
out(' ' .. dep_info.message)
end
if dep_info.new_field then
out('')
local opts_key, field = dep_info.new_field:match('(.*)%.(.*)')
if opts_key and field then
out((' Please instead use the field `%s` in |gitsigns-config-%s|.'):format(field, opts_key))
out(
(' Please instead use the field `%s` in |gitsigns-config-%s|.'):format(field, opts_key)
)
else
out((' Please instead use |gitsigns-config-%s|.'):format(dep_info.new_field))
end
Expand All @@ -72,6 +76,8 @@ local function gen_config_doc_deprecated(dep_info, out)
out('')
end

--- @param field string
--- @param out fun(_: string?)
local function gen_config_doc_field(field, out)
local v = config.schema[field]

Expand All @@ -84,8 +90,9 @@ local function gen_config_doc_field(field, out)
out(('%78s'):format(t))
end

if v.deprecated then
gen_config_doc_deprecated(v.deprecated, out)
local deprecated = v.deprecated
if deprecated then
gen_config_doc_deprecated(deprecated, out)
end

if v.description then
Expand All @@ -101,16 +108,17 @@ local function gen_config_doc_field(field, out)
if v.type == 'table' and v.deep_extend then
return 'table[extended]'
end
if type(v.type) == 'table' then
v.type = table.concat(v.type, '|')
local ty = v.type
if type(ty) == 'table' then
v.type = table.concat(ty, '|')
end
return v.type
end)()

if d:find('\n') then
out((' Type: `%s`'):format(vtype))
out(' Default: >')
out(' '..d:gsub('\n([^\n\r])', '\n %1'))
out(' ' .. d:gsub('\n([^\n\r])', '\n %1'))
out('<')
else
out((' Type: `%s`, Default: %s'):format(vtype, d))
Expand All @@ -124,9 +132,11 @@ end
--- @return string
local function gen_config_doc()
local res = {} ---@type string[]

local function out(line)
res[#res+1] = line or ''
res[#res + 1] = line or ''
end

for _, k in ipairs(get_ordered_schema_keys()) do
gen_config_doc_field(k, out)
end
Expand All @@ -138,21 +148,20 @@ end
local function parse_func_header(line)
local func = line:match('%w+%.([%w_]+)')
if not func then
error('Unable to parse: '..line)
error('Unable to parse: ' .. line)
end
local args_raw =
line:match('function%((.*)%)') or -- M.name = function(args)
line:match('function%s+%w+%.[%w_]+%((.*)%)') -- function M.name(args)
local args = {}
for k in string.gmatch(args_raw, "([%w_]+)") do
local args_raw = line:match('function%((.*)%)') -- M.name = function(args)
or line:match('function%s+%w+%.[%w_]+%((.*)%)') -- function M.name(args)
local args = {} --- @type string[]
for k in string.gmatch(args_raw, '([%w_]+)') do
if k:sub(1, 1) ~= '_' then
args[#args+1] = string.format('{%s}', k)
args[#args + 1] = string.format('{%s}', k)
end
end
return string.format(
'%-40s%38s',
string.format('%s(%s)', func, table.concat(args, ', ')),
'*gitsigns.'..func..'()*'
'*gitsigns.' .. func .. '()*'
)
end

Expand All @@ -161,8 +170,8 @@ end
--- @return string? type
--- @return string? description
local function parse_param(x)
local name, ty, des = x:match('([^ ]+) +([^ ]+) *(.*)')
return name, ty, des
local name, ty, des = x:match('([^ ]+) +([^ ]+) *(.*)')
return name, ty, des
end

--- @param x string[]
Expand All @@ -178,7 +187,7 @@ local function trim_lines(x)

local r = {} --- @type string[]
for _, e in ipairs(x) do
r[#r+1] = e:sub(min_pad + 1)
r[#r + 1] = e:sub(min_pad + 1)
end

return r
Expand All @@ -196,7 +205,7 @@ local function render_param_or_return(name, ty, desc, name_pad)
if name == ':' then
name_str = ''
else
local nf = '%-'..tostring(name_pad)..'s'
local nf = '%-' .. tostring(name_pad) .. 's'
name_str = nf:format(string.format('{%s} ', name))
end

Expand All @@ -206,12 +215,12 @@ local function render_param_or_return(name, ty, desc, name_pad)

local r = {} --- @type string[]

local desc1 = desc[1] == '' and '' or ' '..desc[1]
r[#r+1] = string.format(' %s(%s): %s', name_str, ty, desc1)
local desc1 = desc[1] == '' and '' or ' ' .. desc[1]
r[#r + 1] = string.format(' %s(%s): %s', name_str, ty, desc1)

local remain_desc = trim_lines(vim.list_slice(desc, 2))
for _, d in ipairs(remain_desc) do
r[#r+1] = ' '..string.rep(' ', name_pad)..d
r[#r + 1] = ' ' .. string.rep(' ', name_pad) .. d
end

return r
Expand All @@ -225,7 +234,7 @@ local function pad(x, amount)

local r = {} --- @type string[]
for _, e in ipairs(x) do
r[#r+1] = pad_str..e
r[#r + 1] = pad_str .. e
end
return r
end
Expand All @@ -245,31 +254,31 @@ local function process_doc_comment(state, doc_comment, desc, params, returns)

if emmy_type == 'param' then
local name, ty, pdesc = parse_param(emmy_str)
params[#params+1] = {name, ty, { pdesc }}
params[#params + 1] = { name, ty, { pdesc } }
return 'in_param'
end

if emmy_type == 'return' then
local ty, name, rdesc = parse_param(emmy_str)
returns[#returns+1] = {name, ty, { rdesc }}
returns[#returns + 1] = { name, ty, { rdesc } }
return 'in_return'
end

if state == 'in_param' then
-- Consume any remaining doc document lines as the description for the
-- last parameter
local lastdes = params[#params][3]
lastdes[#lastdes+1] = doc_comment
lastdes[#lastdes + 1] = doc_comment
elseif state == 'in_return' then
-- Consume any remaining doc document lines as the description for the
-- last return
local lastdes = returns[#returns][3]
lastdes[#lastdes+1] = doc_comment
lastdes[#lastdes + 1] = doc_comment
else
if doc_comment ~= '' and doc_comment ~= '<' then
doc_comment = string.rep(' ', 16)..doc_comment
doc_comment = string.rep(' ', 16) .. doc_comment
end
desc[#desc+1] = doc_comment
desc[#desc + 1] = doc_comment
end

return state
Expand All @@ -295,7 +304,7 @@ local function render_block(header, block, params, returns)
)

if #params > 0 then
local param_block = {'Parameters: ~'}
local param_block = { 'Parameters: ~' }

local name_pad = 0
for _, v in ipairs(params) do
Expand All @@ -312,8 +321,8 @@ local function render_block(header, block, params, returns)
end

if #returns > 0 then
res[#res+1] = ''
local param_block = {'Returns: ~'}
res[#res + 1] = ''
local param_block = { 'Returns: ~' }
for _, v in ipairs(returns) do
local name, ty, desc = v[1], v[2], v[3]
list_extend(param_block, render_param_or_return(name, ty, desc))
Expand All @@ -327,7 +336,7 @@ end
--- @param path string
--- @return string
local function gen_functions_doc_from_file(path)
local i = read_file(path):gmatch("([^\n]*)\n?") --- @type Iterator[string]
local i = read_file(path):gmatch('([^\n]*)\n?') --- @type Iterator[string]

local blocks = {} --- @type string[][]

Expand All @@ -345,7 +354,7 @@ local function gen_functions_doc_from_file(path)
-- First line after block
local ok, header = pcall(parse_func_header, l)
if ok then
blocks[#blocks+1] = render_block(header, desc, params, returns)
blocks[#blocks + 1] = render_block(header, desc, params, returns)
end
state = 'none'
desc = {}
Expand All @@ -358,9 +367,9 @@ local function gen_functions_doc_from_file(path)
for j = #blocks, 1, -1 do
local b = blocks[j]
for k = 1, #b do
res[#res+1] = b[k]:match('^ *$') and '' or b[k]
res[#res + 1] = b[k]:match('^ *$') and '' or b[k]
end
res[#res+1] = ''
res[#res + 1] = ''
end

return table.concat(res, '\n')
Expand All @@ -369,11 +378,11 @@ end
--- @param files string[]
--- @return string
local function gen_functions_doc(files)
local res = ''
local res = {} --- @type string[]
for _, path in ipairs(files) do
res = res..'\n'..gen_functions_doc_from_file(path)
res[#res + 1] = gen_functions_doc_from_file(path)
end
return res
return table.concat(res, '\n')
end

--- @return string
Expand All @@ -395,16 +404,16 @@ local function gen_highlights_doc()
if not spec.hidden then
local fallbacks_tbl = {} --- @type string[]
for _, f in ipairs(spec) do
fallbacks_tbl[#fallbacks_tbl+1] = string.format('`%s`', f)
fallbacks_tbl[#fallbacks_tbl + 1] = string.format('`%s`', f)
end
local fallbacks = table.concat(fallbacks_tbl, ', ')
res[#res+1] = string.format('%s*hl-%s*', string.rep(' ', 56), name)
res[#res+1] = string.format('%s', name)
res[#res + 1] = string.format('%s*hl-%s*', string.rep(' ', 56), name)
res[#res + 1] = string.format('%s', name)
if spec.desc then
res[#res+1] = string.format('%s%s', string.rep(' ', 8), spec.desc)
res[#res+1] = ''
res[#res + 1] = string.format('%s%s', string.rep(' ', 8), spec.desc)
res[#res + 1] = ''
end
res[#res+1] = string.format('%sFallbacks: %s', string.rep(' ', 8), fallbacks)
res[#res + 1] = string.format('%sFallbacks: %s', string.rep(' ', 8), fallbacks)
end
end
end
Expand All @@ -414,11 +423,11 @@ end

--- @return string
local function get_setup_from_readme()
local readme = read_file('README.md'):gmatch("([^\n]*)\n?") --- @type Iterator
local readme = read_file('README.md'):gmatch('([^\n]*)\n?') --- @type Iterator
local res = {} --- @type string[]

local function append(line)
res[#res+1] = line ~= '' and ' '..line or ''
res[#res + 1] = line ~= '' and ' ' .. line or ''
end

for l in readme do
Expand All @@ -442,22 +451,22 @@ end
--- @return string|fun():string
local function get_marker_text(marker)
return ({
VERSION = '0.7-dev',
CONFIG = function() return gen_config_doc() end,
VERSION = '0.7-dev',
CONFIG = gen_config_doc,
FUNCTIONS = function()
return gen_functions_doc{
return gen_functions_doc({
'lua/gitsigns.lua',
'lua/gitsigns/attach.lua',
'lua/gitsigns/actions.lua',
}
})
end,
HIGHLIGHTS = function() return gen_highlights_doc() end,
SETUP = function() return get_setup_from_readme() end,
HIGHLIGHTS = gen_highlights_doc,
SETUP = get_setup_from_readme,
})[marker]
end

local function main()
local template = read_file('etc/doc_template.txt'):gmatch("([^\n]*)\n?") --- @type Iterator
local template = read_file('etc/doc_template.txt'):gmatch('([^\n]*)\n?') --- @type Iterator

local out = assert(io.open('doc/gitsigns.txt', 'w'))

Expand All @@ -470,7 +479,7 @@ local function main()
sub = sub()
end
sub = sub:gsub('%%', '%%%%')
l = l:gsub('{{'..marker..'}}', sub)
l = l:gsub('{{' .. marker .. '}}', sub)
end
end
out:write(l or '', '\n')
Expand Down

0 comments on commit b7f6c52

Please sign in to comment.