From 3b023ec79dcf01e92b97beb0d6dbd8cbf7ff92fb Mon Sep 17 00:00:00 2001 From: mitchell <70453897+667e-11@users.noreply.github.com> Date: Mon, 28 Feb 2011 23:13:31 -0500 Subject: Readded scripts. --- scripts/adeptsensedoc.lua | 165 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 scripts/adeptsensedoc.lua (limited to 'scripts/adeptsensedoc.lua') diff --git a/scripts/adeptsensedoc.lua b/scripts/adeptsensedoc.lua new file mode 100644 index 00000000..ea4e3359 --- /dev/null +++ b/scripts/adeptsensedoc.lua @@ -0,0 +1,165 @@ +-- Copyright 2007-2011 Mitchell mitchellcaladbolg.net. See LICENSE. + +--- +-- Adeptsense doclet for LuaDoc. +-- This module is used by LuaDoc to create an adeptsense for Lua with a fake +-- ctags file and an api file. +-- Since LuaDoc does not recognize module fields, this doclet parses the Lua +-- files for comments of the form "-- * `field_name`" to generate a field tag. +-- @usage luadoc -d [output_path] -doclet path/to/adeptsensedoc [file(s)] +module('adeptsensedoc', package.seeall) + +local CTAGS_FMT = '%s\t_\t0;"\t%s\t%s' +local string_format = string.format + +-- Writes a ctag. +-- @param file The file to write to. +-- @param name The name of the tag. +-- @param k The kind of ctag. Lua adeptsense uses 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, k, ext_fields) + if type(ext_fields) == 'table' then + ext_fields = table.concat(ext_fields, '\t') + end + file[#file + 1] = string_format(CTAGS_FMT, name, k, ext_fields) +end + +-- Writes a function apidoc. +-- @param file The file to write to. +-- @param m The LuaDoc module object. +-- @param f The LuaDoc function object. +local function write_function_apidoc(file, m, f) + -- Function name. + local name = f.name + if not name:find('[%.:]') then name = m.name..'.'..name end + -- Block documentation for the function. + local doc = { 'fmt -s -w 80 <<"EOF"' } + -- Function arguments. + doc[#doc + 1] = name..'('..table.concat(f.param, ', ')..')' + -- Function description. + doc[#doc + 1] = f.description:gsub('\\n', '\\\\n') + -- Function parameters (@param). + if f.param then + for _, p in ipairs(f.param) do + if f.param[p] and #f.param[p] > 0 then + doc[#doc + 1] = '@param '..f.param[p]:gsub('\\n', '\\\\n') + end + end + end + -- Function usage (@usage). + if f.usage then + if type(f.usage) == 'string' then + doc[#doc + 1] = '@usage '..f.usage + else + for _, u in ipairs(f.usage) do doc[#doc + 1] = '@usage '..u end + end + end + -- Function returns (@return). + if f.ret then doc[#doc + 1] = '@return '..f.ret end + -- See also (@see). + if f.see then + if type(f.see) == 'string' then + doc[#doc + 1] = '@see '..f.see + else + for _, s in ipairs(f.see) do doc[#doc + 1] = '@see '..s end + end + end + -- Format the block documentation. + doc[#doc + 1] = 'EOF' + local p = io.popen(table.concat(doc, '\n')) + doc = p:read('*all'):gsub('\n', '\\n') + p:close() + file[#file + 1] = table.concat({ name:match('[^%.:]+$') , doc }, ' ') +end + +-- Called by LuaDoc to process a doc object. +-- @param doc The LuaDoc doc object. +function start(doc) +-- require 'luarocks.require' +-- local profiler = require 'profiler' +-- profiler.start() + + local modules = doc.modules + + -- Convert module functions in the Lua luadoc into LuaDoc modules. + local lua_luadoc = doc.files['../modules/lua/lua.luadoc'] + if lua_luadoc then + for _, f in ipairs(lua_luadoc.functions) do + f = lua_luadoc.functions[f] + local module = f.name:match('^([^%.]+)%.') or '_G' + if not modules[module] then + modules[#modules + 1] = module + modules[module] = { name = module, functions = {} } + end + local module = modules[module] + module.functions[#module.functions + 1] = f.name + module.functions[f.name] = f + end + end + + -- Parse out module fields (-- * `FIELD`) and insert them into their LuaDoc + -- modules. + for _, file in ipairs(doc.files) do + local p = io.popen('grep -r "^-- \\* \\`" '..file) + local output = p:read('*all') + p:close() + for line in output:gmatch('[^\n]+') do + local field = line:match('^%-%- %* `([^`]+)`') + p = io.popen('grep "^module" '..file) + local module = (p:read('*l') or ''):match("module%('([^']+)'") + p:close() + if not module then module = field:match('^[^%.]+') end -- lua.luadoc + local module = modules[module] + if not module.fields then module.fields = {} end + module.fields[#module.fields + 1] = field:match('[^%.]+$') + end + end + + -- Process LuaDoc and write the ctags and api file. + local ctags, apidoc = {}, {} + for _, m in ipairs(modules) do + m = modules[m] + local module = m.name + -- Tag the module. + write_tag(ctags, module, 'm', '') + if module:find('%.') then + -- Tag the last part of the module as a table of the first part. + local parent, child = module:match('^(.-)%.([^%.]+)$') + write_tag(ctags, child, 't', 'class:'..parent) + elseif module ~= '_G' then + -- Tag the module as a global table. + write_tag(ctags, module, 't', 'class:_G') + write_tag(ctags, module, 't', '') + end + -- Tag the functions and write the apidoc. + for _, f in ipairs(m.functions) do + if not f:find('no_functions') then -- ignore placeholders + local func = f:match('[^%.:]+$') + write_tag(ctags, func, 'f', 'class:'..module) + if module == '_G' then write_tag(ctags, func, 'f', '') end -- global + write_function_apidoc(apidoc, m, m.functions[f]) + end + end + -- Tag the tables. + for _, t in ipairs(m.tables or {}) do + write_tag(ctags, t, 't', 'class:'..module) + if module == '_G' then write_tag(ctags, t, 't', '') end -- global + end + -- Tag the fields. + for _, f in ipairs(m.fields or {}) do + write_tag(ctags, f, 'F', 'class:'..module) + if module == '_G' then write_tag(ctags, f, 'F', '') end -- global + end + end + local f = io.open(options.output_dir..'/tags', 'w') + f:write(table.concat(ctags, '\n')) + f:close() + f = io.open(options.output_dir..'api', 'w') + f:write(table.concat(apidoc, '\n')) + f:close() + +-- profiler.stop() +end + +return _M -- cgit v1.2.3