diff options
Diffstat (limited to 'modules/lua/tadoc.lua')
| -rw-r--r-- | modules/lua/tadoc.lua | 90 |
1 files changed, 37 insertions, 53 deletions
diff --git a/modules/lua/tadoc.lua b/modules/lua/tadoc.lua index f4ba1b93..8404364f 100644 --- a/modules/lua/tadoc.lua +++ b/modules/lua/tadoc.lua @@ -1,11 +1,10 @@ -- Copyright 2007-2021 Mitchell. See LICENSE. -- Textadept autocompletions and API documentation doclet for LuaDoc. --- This module is used by LuaDoc to create Lua autocompletion and API --- documentation files that Textadept can read. --- To preserve formatting, the included *luadoc.patch* file must be applied to --- your instance of LuaDoc. It will not affect the look of HTML web pages, only --- the look of plain-text output. +-- This module is used by LuaDoc to create Lua autocompletion and API documentation files that +-- Textadept can read. +-- To preserve formatting, the included *luadoc.patch* file must be applied to your instance +-- of LuaDoc. It will not affect the look of HTML web pages, only the look of plain-text output. -- Also requires LuaFileSystem (lfs) to be installed. -- @usage luadoc -d [output_path] -doclet path/to/tadoc [file(s)] local M = {} @@ -14,13 +13,16 @@ local CTAG = '%s\t%s\t/^%s$/;"\t%s\t%s' local string_format = string.format local lfs = require('lfs') --- As a special case for Textadept API tags, do not store the local path, but --- use a `_HOME` prefix that will be filled in by consumers. Do this by making --- use of a custom command line switch: --ta-home="path/to/ta/home". +-- As a special case for Textadept API tags, do not store the local path, but use a `_HOME` +-- prefix that will be filled in by consumers. Do this by making use of a custom command line +-- switch: --ta-home="path/to/ta/home". local _HOME for i = 1, #arg do _HOME = arg[i]:match('^%-%-ta%-home=(.+)$') - if _HOME then _HOME = _HOME:gsub('%p', '%%%0') break end + if _HOME then + _HOME = _HOME:gsub('%p', '%%%0') + break + end end -- Writes a ctag. @@ -28,8 +30,8 @@ end -- @param name The name of the tag. -- @param filename The filename the tag occurs in. -- @param code The line of code the tag occurs on. --- @param k The kind of ctag. The Lua module recognizes 4 kinds: m Module, f --- Function, t Table, and F Field. +-- @param k The kind of ctag. The Lua module recognizes 4 kinds: m Module, f Function, t Table, +-- and F Field. -- @param ext_fields The ext_fields for the ctag. local function write_tag(file, name, filename, code, k, ext_fields) if _HOME then filename = filename:gsub(_HOME, '_HOME') end @@ -37,16 +39,16 @@ local function write_tag(file, name, filename, code, k, ext_fields) file[#file + 1] = string_format(CTAG, name, filename, code, k, ext_fields) end --- Sanitizes Markdown from the given documentation string by stripping links and --- replacing HTML entities. +-- Sanitizes Markdown from the given documentation string by stripping links and replacing +-- HTML entities. -- @param s String to sanitize Markdown from. -- @return string local function sanitize_markdown(s) return s:gsub('%[([^%]\r\n]+)%]%b[]', '%1') -- [foo][] - :gsub('%[([^%]\r\n]+)%]%b()', '%1') -- [foo](bar) - :gsub('\r?\n\r?\n%[([^%]\r\n]+)%]:[^\r\n]+', '') -- [foo]: bar - :gsub('\r?\n%[([^%]\r\n]+)%]:[^\r\n]+', '') -- [foo]: bar - :gsub('&([%a]+);', {quot = '"', apos = "'"}) + :gsub('%[([^%]\r\n]+)%]%b()', '%1') -- [foo](bar) + :gsub('\r?\n\r?\n%[([^%]\r\n]+)%]:[^\r\n]+', '') -- [foo]: bar + :gsub('\r?\n%[([^%]\r\n]+)%]:[^\r\n]+', '') -- [foo]: bar + :gsub('&([%a]+);', {quot = '"', apos = "'"}) end -- Writes a function or field apidoc. @@ -63,8 +65,7 @@ local function write_apidoc(file, m, b) local class = b.class local header = name if class == 'function' then - header = header .. - (b.param and string.format('(%s)', table.concat(b.param, ', ')) or '') + header = header .. (b.param and string.format('(%s)', table.concat(b.param, ', ')) or '') elseif class == 'field' and b.description:find('^%s*%b()') then header = string.format('%s %s', header, b.description:match('^%s*(%b())')) elseif class == 'module' or class == 'table' then @@ -74,8 +75,8 @@ local function write_apidoc(file, m, b) -- Function or field description. local description = b.description if class == 'module' then - -- Modules usually have additional Markdown documentation so just grab the - -- documentation before a Markdown header. + -- Modules usually have additional Markdown documentation so just grab the documentation + -- before a Markdown header. description = description:match('^(.-)[\r\n]+#') or description elseif class == 'field' then -- Type information is already in the header; discard it in the description. @@ -83,17 +84,14 @@ local function write_apidoc(file, m, b) -- Strip consistent leading whitespace. local indent indent, description = description:match('^(%s*)(.*)$') - if indent ~= '' then - description = description:gsub('\n' .. indent, '\n') - end + if indent ~= '' then description = description:gsub('\n' .. indent, '\n') end end doc[#doc + 1] = sanitize_markdown(description) -- Function parameters (@param). if class == 'function' and b.param then for _, p in ipairs(b.param) do if b.param[p] and #b.param[p] > 0 then - doc[#doc + 1] = string.format( - '@param %s %s', p, sanitize_markdown(b.param[p])) + doc[#doc + 1] = string.format('@param %s %s', p, sanitize_markdown(b.param[p])) end end end @@ -141,9 +139,9 @@ end -- Called by LuaDoc to process a doc object. -- @param doc The LuaDoc doc object. function M.start(doc) --- require('luarocks.require') --- local profiler = require('profiler') --- profiler.start() + -- require('luarocks.require') + -- local profiler = require('profiler') + -- profiler.start() local modules, files = doc.modules, doc.files @@ -156,8 +154,7 @@ function M.start(doc) -- Add a module's fields to its LuaDoc. for _, filename in ipairs(files) do local module_doc = files[filename].doc[1] - if module_doc and module_doc.class == 'module' and - modules[module_doc.name] then + if module_doc and module_doc.class == 'module' and modules[module_doc.name] then modules[module_doc.name].fields = module_doc.field elseif module_doc then print(string.format('[WARN] %s has no module declaration', filename)) @@ -172,9 +169,7 @@ function M.start(doc) local module_name = func.name:match('^([^%.:]+)[%.:]') or '_G' if not modules[module_name] then modules[#modules + 1] = module_name - modules[module_name] = { - name = module_name, functions = {}, doc = {{code = func.code}} - } + modules[module_name] = {name = module_name, functions = {}, doc = {{code = func.code}}} files[modules[module_name].doc] = abspath(files[1]) -- For functions like file:read(), 'file' is not a module; fake it. if func.name:find(':') then modules[module_name].fake = true end @@ -206,8 +201,7 @@ function M.start(doc) if m.name:find('%.') then -- Tag the last part of the module as a table of the first part. local parent, child = m.name:match('^(.-)%.([^%.]+)$') - write_tag( - ctags, child, filename, m.doc[1].code[1], 'm', 'class:' .. parent) + write_tag(ctags, child, filename, m.doc[1].code[1], 'm', 'class:' .. parent) end m.class = 'module' write_apidoc(apidoc, {name = '_G'}, m) @@ -217,8 +211,7 @@ function M.start(doc) local module_name, name = function_name:match('^(.-)[%.:]?([^.:]+)$') if module_name == '' then module_name = m.name end local func = m.functions[function_name] - write_tag( - ctags, name, filename, func.code[1], 'f', 'class:' .. module_name) + write_tag(ctags, name, filename, func.code[1], 'f', 'class:' .. module_name) write_apidoc(apidoc, m, func) end if m.tables then @@ -234,21 +227,15 @@ function M.start(doc) module_name = '_G' -- _G.keys or _G.snippets end end - write_tag( - ctags, table_name, filename, table.code[1], 't', - 'class:' .. module_name) + write_tag(ctags, table_name, filename, table.code[1], 't', 'class:' .. module_name) write_apidoc(apidoc, m, table) if table.field then -- Tag and document the table's fields. table_name = string.format('%s.%s', module_name, table_name) for _, field_name in ipairs(table.field) do - write_tag( - ctags, field_name, filename, table.code[1], 'F', - 'class:' .. table_name) + write_tag(ctags, field_name, filename, table.code[1], 'F', 'class:' .. table_name) write_apidoc(apidoc, {name = table_name}, { - name = field_name, - description = table.field[field_name], - class = 'table' + name = field_name, description = table.field[field_name], class = 'table' }) end end @@ -265,12 +252,9 @@ function M.start(doc) print('[ERROR] Cannot determine module name for ' .. field.name) end end - write_tag( - ctags, field_name, filename, m.doc[1].code[1], 'F', - 'class:' .. module_name) + write_tag(ctags, field_name, filename, m.doc[1].code[1], 'F', 'class:' .. module_name) write_apidoc(apidoc, {name = field_name}, { - name = string.format('%s.%s', module_name, field_name), - description = field, + name = string.format('%s.%s', module_name, field_name), description = field, class = 'field' }) end @@ -285,7 +269,7 @@ function M.start(doc) f:write(table.concat(apidoc, '\n')) f:close() --- profiler.stop() + -- profiler.stop() end return M |