1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
-- Copyright 2007-2022 Mitchell. See LICENSE.
-- Markdown doclet for Luadoc.
-- @usage luadoc -doclet path/to/markdowndoc [file(s)] > api.md
local M = {}
local TOC = '1. [%s](%s)\n'
local MODULE = '<a id="%s"></a>\n## The `%s` Module\n'
local FIELD = '<a id="%s"></a>\n#### `%s` %s\n\n'
local FUNCTION = '<a id="%s"></a>\n#### `%s`(*%s*)\n\n'
local FUNCTION_NO_PARAMS = '<a id="%s"></a>\n#### `%s`()\n\n'
local DESCRIPTION = '%s\n\n'
local LIST_TITLE = '%s:\n\n'
local PARAM = '* *`%s`*: %s\n'
local USAGE = '* `%s`\n'
local RETURN = '* %s\n'
local SEE = '* [`%s`](#%s)\n'
local TABLE = '<a id="%s"></a>\n#### `%s`\n\n'
local TFIELD = '* `%s`: %s\n'
local titles = {
[PARAM] = 'Parameters', [USAGE] = 'Usage', [RETURN] = 'Return', [SEE] = 'See also',
[TFIELD] = 'Fields'
}
-- Writes a LuaDoc description to the given file.
-- @param f The markdown file being written to.
-- @param description The description.
-- @param name The name of the module the description belongs to. Used for headers in module
-- descriptions.
local function write_description(f, description, name)
-- Substitute custom [`code`]() link convention with [`code`](#code) links.
local self_link = '(%[`([^`(]+)%(?%)?`%])%(%)'
description = description:gsub(self_link, function(link, id)
return string.format('%s(#%s)', link, id:gsub(':', '.'))
end)
f:write(string.format(DESCRIPTION, description))
end
-- Writes a LuaDoc list to the given file.
-- @param f The markdown file being written to.
-- @param fmt The format of a list item.
-- @param list The LuaDoc list.
-- @param name The name of the module the list belongs to. Used for @see.
local function write_list(f, fmt, list, name)
if not list or #list == 0 then return end
if type(list) == 'string' then list = {list} end
f:write(string.format(LIST_TITLE, titles[fmt]))
for _, value in ipairs(list) do
if fmt == SEE and name ~= '_G' then
if not value:find('%.') then
-- Prepend module name to identifier if necessary.
value = name .. '.' .. value
else
-- TODO: cannot link to fields, functions, or tables in `_G`?
value = value:gsub('^_G%.', '')
end
end
f:write(string.format(fmt, value, value))
end
f:write('\n')
end
-- Writes a LuaDoc hashmap to the given file.
-- @param f The markdown file being written to.
-- @param fmt The format of a hashmap item.
-- @param list The LuaDoc hashmap.
local function write_hashmap(f, fmt, hashmap)
if not hashmap or #hashmap == 0 then return end
f:write(string.format(LIST_TITLE, titles[fmt]))
for _, name in ipairs(hashmap) do f:write(string.format(fmt, name, hashmap[name] or '')) end
f:write('\n')
end
-- Called by LuaDoc to process a doc object.
-- @param doc The LuaDoc doc object.
function M.start(doc)
local modules, files = doc.modules, doc.files
local f = io.stdout
f:write('## Textadept API Documentation\n\n')
-- Create the table of contents.
for _, name in ipairs(modules) do f:write(string.format(TOC, name, '#' .. name)) end
f:write('\n')
-- Create a map of doc objects to file names so their Markdown doc comments can be extracted.
local filedocs = {}
for _, name in ipairs(files) do filedocs[files[name].doc] = name end
-- Loop over modules, writing the Markdown document to stdout.
for _, name in ipairs(modules) do
local module = modules[name]
-- Write the header and description.
f:write(string.format(MODULE, name, name))
f:write('---\n\n')
write_description(f, module.description, name)
-- Write fields.
if module.doc[1].class == 'module' then
local fields = module.doc[1].field
if fields and #fields > 0 then
table.sort(fields)
f:write('### Fields defined by `', name, '`\n\n')
for _, field in ipairs(fields) do
local type, description = fields[field]:match('^(%b())%s*(.+)$')
if not field:find('%.') and name ~= '_G' then
field = name .. '.' .. field -- absolute name
else
field = field:gsub('^_G%.', '') -- strip _G required for Luadoc
end
f:write(string.format(FIELD, field, field, type or ''))
write_description(f, description or fields[field])
end
f:write('\n')
end
end
-- Write functions.
local funcs = module.functions
if #funcs > 0 then
f:write('### Functions defined by `', name, '`\n\n')
for _, fname in ipairs(funcs) do
local func = funcs[fname]
local params = table.concat(func.param, ', '):gsub('_', '\\_')
if not func.name:find('[%.:]') and name ~= '_G' then
func.name = name .. '.' .. func.name -- absolute name
end
if params ~= '' then
f:write(string.format(FUNCTION, func.name, func.name, params))
else
f:write(string.format(FUNCTION_NO_PARAMS, func.name, func.name))
end
write_description(f, func.description)
write_hashmap(f, PARAM, func.param)
write_list(f, USAGE, func.usage)
write_list(f, RETURN, func.ret)
write_list(f, SEE, func.see, name)
end
f:write('\n')
end
-- Write tables.
local tables = module.tables
if #tables > 0 then
f:write('### Tables defined by `', name, '`\n\n')
for _, tname in ipairs(tables) do
local tbl = tables[tname]
if not tname:find('%.') and (name ~= '_G' or tname == 'buffer' or tname == 'view') then
tname = name .. '.' .. tname -- absolute name
elseif tname ~= '_G.keys' and tname ~= '_G.snippets' then
tname = tname:gsub('^_G%.', '') -- strip _G required for Luadoc
end
f:write(string.format(TABLE, tname, tname))
write_description(f, tbl.description)
write_hashmap(f, TFIELD, tbl.field)
write_list(f, USAGE, tbl.usage)
write_list(f, SEE, tbl.see, name)
end
end
f:write('---\n')
end
end
return M
|
