Merge pull request #331 from alerque/lint-and-test

.github/workflows/luacheck.yml

@@ -0,0 +1,23 @@
+name: Luacheck
+
+on: [push, pull_request]
+
+jobs:
+  luacheck:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+    - name: Setup Lua
+      uses: leafo/gh-actions-lua@v6
+      with:
+        luaVersion: 5.4
+    - name: Setup Lua Rocks
+      uses: leafo/gh-actions-luarocks@v2
+    - name: Setup dependencies
+      run: luarocks install luacheck
+    - name: Run Code Linter
+      run: |
+        luacheck .
+        luarocks lint *.rockspec

.luacheckrc

@@ -0,0 +1,21 @@
+unused_args     = false
+redefined       = false
+max_line_length = false
+
+include_files = {
+  "**/*.lua",
+  "*.rockspec",
+  ".luacheckrc",
+}
+
+exclude_files = {
+  -- Tests are too messy to lint
+    "tests",
+  -- Travis Lua environment
+    "here/*.lua",
+  "here/**/*.lua",
+  -- GH Actions Lua Environment
+    ".lua",
+  ".luarocks",
+  ".install",
+}

Makefile

@@ -3,6 +3,8 @@ LUA_BINDIR= $(shell echo `dirname $(LUA)`)
 LUA_PREFIX= $(shell echo `dirname $(LUA_BINDIR)`)
 LUA_SHAREDIR=$(LUA_PREFIX)/share/lua/5.1
 
+_REPODIR != cd "$(shell dirname $(firstword $(MAKEFILE_LIST)))/" && pwd
+
 ldoc:
 
 install: install_parts
@@ -28,23 +30,26 @@ uninstall:
 
 test: test-basic test-example test-md test-tables
 
-RUN=&&  ldoc . && diff -r docs cdocs && echo ok
+RUN=&& lua $(_REPODIR)/ldoc.lua . && diff -r doc cdocs && echo ok
+
+test-prep:
+	find -type d -name doc -execdir rsync -av --del {}/ cdocs/ \;
 
 test-basic:
 	cd tests $(RUN)
 
 test-example:
-	cd tests && cd example $(RUN)
+	cd tests/example $(RUN)
 
 test-md:
-	cd tests && cd md-test $(RUN)
+	cd tests/md-test $(RUN)
 
 test-tables:
-	cd tests && cd simple $(RUN)
+	cd tests/simple $(RUN)
 
 test-clean: clean-basic clean-example clean-md clean-tables
 
-CLEAN=&& ldoc . && rd /S /Q cdocs && cp -rf docs cdocs
+CLEAN=&& lua $(_REPODIR)/ldoc.lua . && rd /S /Q cdocs && cp -rf doc cdocs
 
 clean-basic:
 	cd tests $(CLEAN)

README.md

@@ -1,5 +1,7 @@
 # LDoc - A Lua Documentation Tool
 
+[![Luacheck](https://github.com/lunarmodules/LDoc/workflows/Luacheck/badge.svg)](https://github.com/lunarmodules/LDoc/actions)
+
 Copyright (C) 2011-2012 Steve Donovan.
 
 ## Rationale

ldoc.lua

@@ -27,7 +27,6 @@ local tablex = require 'pl.tablex'
 
 -- Penlight compatibility
 utils.unpack = utils.unpack or unpack or table.unpack
-local append = table.insert
 local lapp = require 'pl.lapp'
 
 local version = '1.4.6'
@@ -91,7 +90,7 @@ local global = require 'ldoc.builtin.globals'
 local markup = require 'ldoc.markup'
 local parse = require 'ldoc.parse'
 local KindMap = tools.KindMap
-local Item,File,Module = doc.Item,doc.File,doc.Module
+local Item,File = doc.Item,doc.File
 local quit = utils.quit
 
 if args.version then
@@ -176,7 +175,6 @@ local function setup_kinds ()
 end
 
 
-local add_language_extension
 -- hacky way for doc module to be passed options...
 doc.ldoc = ldoc
 
@@ -258,14 +256,15 @@ ldoc_contents = tablex.makeset(ldoc_contents)
 
 local function loadstr (ldoc,txt)
    local chunk, err
-   local load
    -- Penlight's Lua 5.2 compatibility has wobbled over the years...
    if not rawget(_G,'loadin') then -- Penlight 0.9.5
        -- Penlight 0.9.7; no more global load() override
-      load = load or utils.load
+      local load = load or utils.load
       chunk,err = load(txt,'config',nil,ldoc)
    else
+      -- luacheck: push ignore 113
       chunk,err = loadin(ldoc,txt)
+      -- luacheck: pop
    end
    return chunk, err
 end
@@ -277,7 +276,7 @@ local function read_ldoc_config (fname)
    if directory == '' then
       directory = '.'
    end
-   local chunk, err, ok
+   local chunk, err, _
    if args.filter == 'none' then
       print('reading configuration from '..fname)
    end
@@ -286,7 +285,7 @@ local function read_ldoc_config (fname)
       chunk, err = loadstr(ldoc,txt)
       if chunk then
          if args.define ~= 'none' then ldoc[args.define] = true end
-         ok,err = pcall(chunk)
+         _,err = pcall(chunk)
       end
     end
    if err then quit('error loading config file '..fname..': '..err) end
@@ -301,7 +300,6 @@ end
 local quote = tools.quote
 --- processing command line and preparing for output ---
 
-local F
 local file_list = List()
 File.list = file_list
 local config_dir
@@ -316,7 +314,7 @@ if args.module then
    if args.file:match '^%a+$' and global.functions[args.file] then
       args.file = 'global.'..args.file
    end
-   local fullpath,mod,on_docpath = tools.lookup_existing_module_or_function (args.file, doc_path)
+   local fullpath,mod,_ = tools.lookup_existing_module_or_function (args.file, doc_path)
    if not fullpath then
       quit(mod)
    else
@@ -337,7 +335,6 @@ if args.file == '.' then
       print('changing to directory',config_path)
       lfs.chdir(config_path)
    end
-   config_is_read = true
    args.file = ldoc.file or '.'
    if args.file == '.' then
       args.file = lfs.currentdir()

ldoc/builtin/debug.lua

@@ -43,18 +43,18 @@ function debug.gethook(thread) end
 -- with a name for the current function, if a reasonable name can be found,
 -- and the expression `debug.getinfo(print)` returns a table with all available
 -- information about the `print` function.
-function debug.getinfo(thread, function , what) end
+function debug.getinfo(thread, func , what) end
 
 ---
 -- This function returns the name and the value of the local variable with
--- index `local` of the function at level `level` of the stack. (The first
+-- index `loc` of the function at level `level` of the stack. (The first
 -- parameter or local variable has index 1, and so on, until the last active
 -- local variable.) The function returns nil if there is no local variable
 -- with the given index, and raises an error when called with a `level` out
 -- of range. (You can call `debug.getinfo` to check whether the level is valid.)
 -- Variable names starting with '`(`' (open parentheses) represent internal
 -- variables (loop control variables, temporaries, and C function locals).
-function debug.getlocal(thread, level, local) end
+function debug.getlocal(thread, level, loc) end
 
 ---
 -- Returns the metatable of the given `object` or nil if it does not have
@@ -103,12 +103,12 @@ function debug.sethook(thread, hook, mask , count) end
 
 ---
 -- This function assigns the value `value` to the local variable with
--- index `local` of the function at level `level` of the stack. The function
+-- index `loc` of the function at level `level` of the stack. The function
 -- returns nil if there is no local variable with the given index, and raises
 -- an error when called with a `level` out of range. (You can call `getinfo`
 -- to check whether the level is valid.) Otherwise, it returns the name of
 -- the local variable.
-function debug.setlocal(thread, level, local, value) end
+function debug.setlocal(thread, level, loc, value) end
 
 ---
 -- Sets the metatable for the given `object` to the given `table` (which

ldoc/builtin/global.lua

@@ -2,6 +2,8 @@
 
 module 'global'
 
+-- luacheck: ignore 121
+
 ---
 -- Issues an error when  its argument `v` is false.
 -- That is, nil or false. otherwise, returns all its arguments.
@@ -83,12 +85,12 @@ function ipairs(t) end
 -- The string `mode` controls whether the chunk can be text or binary (that is, a precompiled chunk).
 -- It may be the string "b" (only binary chunks), "t" (only text chunks), or "bt" (both binary and text).
 -- The default is "bt"
-function load (ld [, source [, mode [, env]]]) end
+function load (ld , source , mode , env) end
 
 ---
 -- Similar to `load`, but gets the chunk from file `filename`. Or from the
 -- standard input, if no file name is given.
-function loadfile (filename [, mode [, env]]]) end
+function loadfile (filename , mode , env) end
 
 ---
 -- Allows a program to traverse all fields of a table. Its first argument is
@@ -178,7 +180,7 @@ function setmetatable(table, metatable) end
 -- 11, and so forth, with '`Z`' representing 35. In base 10 (the default),
 -- the number can have a decimal part, as well as an optional exponent part
 -- (see 2.1). In other bases, only unsigned integers are accepted.
-function tonumber(e [, base]) end
+function tonumber(e , base) end
 
 ---
 -- Converts any value to a string in a reasonable format.

ldoc/builtin/io.lua

@@ -3,6 +3,9 @@
 
 local io = {}
 
+-- luacheck: ignore 241
+local file = {}
+
 ---
 -- Equivalent to `file:close()`. Without a `file`, closes the default
 -- output file.

ldoc/builtin/string.lua

@@ -21,7 +21,7 @@ function string.char(...) end
 -- Returns a string containing a binary representation of the given
 -- function, so that a later `loadstring` on this string returns a copy of
 -- the function. `function` must be a Lua function without upvalues.
-function string.dump(function) end
+function string.dump(func) end
 
 ---
 -- Looks for the first match of `pattern` in the string `s`. If it finds a
@@ -174,7 +174,7 @@ function string.upper(s) end
 ---
 -- (5.3) Returns a binary string containing the values v1, v2, etc. packed (that is, serialized in binary form)
 --- according to the format string fmt (see 6.4.2).
-function string.pack (fmt, v1, v2, ···) end
+function string.pack (fmt, v1, v2, ...) end
 
 ---
 -- (5.3) Returns the size of a string resulting from string.pack with the given format.
@@ -185,7 +185,7 @@ function string.packsize (fmt) end
 -- (5.3) Returns the values packed in string s (see string.pack) according to the format string fmt (see 6.4.2).
 -- An optional pos marks where to start reading in s (default is 1)
 -- After the read values, this function also returns the index of the first unread byte in s.
-function string.unpack (fmt, s [, pos]) end
+function string.unpack (fmt, s , pos) end
 
 return string
 

ldoc/builtin/table.lua

@@ -29,7 +29,7 @@ function table.remove(table , pos) end
 ---
 -- Returns a new table with all parameters stored into keys 1, 2, etc. and with a field "n" with
 -- the total number of parameters. Note that the resulting table may not be a sequence.
-function table.pack (···) end
+function table.pack (...) end
 ---
 -- Sorts table elements in a given order,
 -- *in-place*, from `table[1]` to `table[n]`, where `n` is the length of the
@@ -39,6 +39,8 @@ function table.pack (···) end
 -- is not given, then the '<' operator will be used.
 function table.sort(table , comp) end
 
+-- luacheck: ignore 121
+
 ---
 -- Returns the elements from the given table. This function is equivalent to
 --   return list[i], list[i+1], ..., list[j]

ldoc/builtin/utf8.lua

@@ -25,13 +25,13 @@ function utf8.codes (s) end
 ---
 -- Returns the codepoints (as integers) from all characters in s that start between byte position i and j (both included).
 -- The default for i is 1 and for j is i. It raises an error if it meets any invalid byte sequence.
-function utf8.codepoint (s [, i [, j]]) end
+function utf8.codepoint (s , i , j) end
 
 ---
 -- Returns the number of UTF-8 characters in string s that start between positions i and j (both inclusive).
 -- The default for i is 1 and for j is -1. If it finds any invalid byte sequence, returns a false value plus
 -- the position of the first invalid byte.
-function utf8.len (s [, i [, j]]) end
+function utf8.len (s , i , j) end
 
 ---
 -- Returns the position (in bytes) where the encoding of the n-th character of s (counting from position i) starts.
@@ -43,6 +43,6 @@ function utf8.len (s [, i [, j]]) end
 -- As a special case, when n is 0 the function returns the start of the encoding of the character that contains the i-th byte of s.
 --
 -- This function assumes that s is a valid UTF-8 string.
-function utf8.offset (s, n [, i]) end
+function utf8.offset (s, n , i) end
-
 
+return utf8

ldoc/doc.lua

@@ -192,12 +192,6 @@ function File:export_item (name)
    self:warning('no docs '..tools.quote(name))
 end
 
-
-local function has_prefix (name,prefix)
-   local i1,i2 = name:find(prefix)
-   return i1 == 1 and i2 == #prefix
-end
-
 local function mod_section_type (this_mod)
    return this_mod and this_mod.section and this_mod.section.type
 end
@@ -236,6 +230,7 @@ function File:finish()
       end
       item:finish()
       -- the default is not to show local functions in the documentation.
+      -- luacheck: push ignore 542
       if not self.args.all and (item.type=='lfunction' or (item.tags and item.tags['local'])) then
          -- don't add to the module --
       elseif doc.project_level(item.type) then
@@ -257,9 +252,9 @@ function File:finish()
                end
             end
          elseif item.type == 'submodule' then
-            local mf
+            local _
             submodule = true
-            this_mod,mf = self:find_module_in_files(item.name)
+            this_mod,_ = self:find_module_in_files(item.name)
             if this_mod == nil then
                self:error("'"..item.name.."' not found for submodule")
             end
@@ -409,6 +404,7 @@ function File:finish()
             -- must be a free-standing function (sometimes a problem...)
          end
       end
+      -- luacheck: pop
       item.names_hierarchy = require('pl.utils').split(
         item.name,
         '[.:]'
@@ -495,7 +491,6 @@ function Item:set_tag (tag,value)
       end
       self.tags[tag] = value
    elseif ttype == TAG_ID then
-      local modifiers
       if type(value) == 'table' then
          if value.append then -- it was a List!
             -- such tags are _not_ multiple, e.g. name
@@ -506,7 +501,6 @@ function Item:set_tag (tag,value)
             end
          end
          value = value[1]
-         modifiers = value.modifiers
       end
       if value == nil then self:error("Tag without value: "..tag) end
       local id, rest = tools.extract_identifier(value)
@@ -543,17 +537,13 @@ function Item.check_tag(tags,tag, value, modifiers)
          if avalue then value = avalue..' '..value end
          if amod then
             modifiers = modifiers or {}
-            local value_tokens = utils.split(value)
             for m,v in pairs(amod) do
                local idx = tonumber(v:match('^%$(%d+)'))
                if idx then
                   v, value = value:match('(%S+)(.*)')
-               --   v = value_tokens[idx]
-               --   value_tokens[idx] = ''
                end
                modifiers[m] = v
             end
-            -- value = table.concat(value_tokens, ' ')
          end
       else -- has to be a function that at least returns tag, value
          return alias(tags,value,modifiers)
@@ -927,8 +917,6 @@ function Item:return_type(r)
    return r.type, r.ctypes
 end
 
-local struct_return_type = '*'
-
 function Item:build_return_groups()
    local quote = tools.quote
    local modifiers = self.modifiers
@@ -1062,8 +1050,6 @@ function Module:hunt_for_reference (packmod, modules)
    return mod_ref
 end
 
-local err = io.stderr
-
 local function custom_see_references (s)
    for pat, action in pairs(see_reference_handlers) do
       if s:match(pat) then
@@ -1099,7 +1085,7 @@ end
 
 function Module:process_see_reference (s,modules,istype)
    if s == nil then return nil end
-   local mod_ref,fun_ref,name,packmod
+   local fun_ref
    local ref = custom_see_references(s)
    if ref then return ref end
    if not s:match '^[%w_%.\\%:%-]+$' or not s:match '[%w_]$' then
@@ -1301,7 +1287,6 @@ function File:dump(verbose)
 end
 
 function Item:dump(verbose)
-   local tags = self.tags
    local name = self.name
    if self.type == 'function' then
       name = name .. self.args

ldoc/html.lua

@@ -154,7 +154,7 @@ function html.generate_output(ldoc, args, project)
    end
 
    function ldoc.include_file (file)
-      local text,e = utils.readfile(file)
+      local text,_ = utils.readfile(file)
       if not text then quit("unable to include "..file)
       else
          return text
@@ -234,7 +234,7 @@ function ldoc.source_ref (fun)
       local types = {}
       for name in tp:gmatch("[^|]+") do
          local sym = name:match '([%w%.%:]+)'
-         local ref,err = markup.process_reference(sym,true)
+         local ref,_ = markup.process_reference(sym,true)
          if ref then
             if ref.label and sym == name then
                name = ref.label
@@ -273,7 +273,7 @@ function ldoc.source_ref (fun)
       ldoc.doc_charset = (m and m.tags.charset) or ldoc.charset
    end
 
-   local module_template,err = utils.readfile (path.join(args.template,ldoc.templ))
+   local module_template,_ = utils.readfile (path.join(args.template,ldoc.templ))
    if not module_template then
       quit("template not found at '"..args.template.."' Use -l to specify directory containing ldoc.ltp")
    end

ldoc/lang.lua

@@ -93,6 +93,7 @@ function Lua:grab_block_comment(v,tok)
 end
 
 
+-- luacheck: push ignore 312
 function Lua:parse_module_call(tok,t,v)
    t,v = tnext(tok)
    if t == '(' then t,v = tnext(tok) end
@@ -102,6 +103,7 @@ function Lua:parse_module_call(tok,t,v)
       return '...',t,v
    end
 end
+-- luacheck: pop
 
 -- If a module name was not provided, then we look for an explicit module()
 -- call. However, we should not try too hard; if we hit a doc comment then
@@ -150,7 +152,7 @@ function Lua:item_follows(t,v,tok)
       case = 1
       parser = parse_lua_function_header
    elseif t == 'iden' then
-      local name,t,v = tools.get_fun_name(tok,v)
+      local name,t,_ = tools.get_fun_name(tok,v)
       if t ~= '=' then return nil,"not  'name = function,table or value'" end
       t,v = tnext(tok)
       if t == 'keyword' and v == 'function' then -- case [2]
@@ -229,7 +231,7 @@ function Lua:parse_module_modifier (tags, tok, F)
       if tags.class ~= 'field' then return nil,"cannot deduce @usage" end
       local t1= tnext(tok)
       if t1 ~= '[' then return nil, t1..' '..': not a long string' end
-      local t, v = tools.grab_block_comment('',tok,'%]%]')
+      local _, v = tools.grab_block_comment('',tok,'%]%]')
       return true, v, 'usage'
    elseif tags.export then
       if tags.class ~= 'table' then return nil, "cannot deduce @export" end
@@ -285,12 +287,13 @@ function CC:item_follows (t,v,tok)
       return false
    end
    if t == 'iden' or t == 'keyword' then --
+      local _
       if v == self.extra.export then -- this is not part of the return type!
-         t,v = tnext(tok)
+         _,v = tnext(tok)
       end
       -- types may have multiple tokens: example, const char *bonzo(...)
       local return_type, name = v
-      t,v = tnext(tok)
+      _,v = tnext(tok)
       name = v
       t,v = tnext(tok)
       while t ~= '(' do
@@ -305,7 +308,7 @@ function CC:item_follows (t,v,tok)
          end
          tags:add('class','function')
          if t == '(' then
-            tags.formal_args,t,v = tools.get_parameters(tok,')',',',self)
+            tags.formal_args,t,_ = tools.get_parameters(tok,')',',',self)
             if return_type ~= 'void' then
                tags.formal_args.return_type = return_type
             end
@@ -342,30 +345,28 @@ function Moon:item_follows (t,v,tok)
    if t == 'iden' then
       local name,t,v = tools.get_fun_name(tok,v,'')
       if name == 'class' then
-         name,t,v = tools.get_fun_name(tok,v,'')
+         local _
+         name,_,_ = tools.get_fun_name(tok,v,'')
          -- class!
          return function(tags,tok)
             tags:add('class','type')
             tags:add('name',name)
          end
       elseif t == '=' or t == ':' then -- function/method
-         local fat = false
+         local _
-         t,v = tnext(tok)
+         t,_ = tnext(tok)
          return function(tags,tok)
             if not tags.name then
                tags:add('name',name)
             end
             if t == '(' then
-               tags.formal_args,t,v = tools.get_parameters(tok,')',',',self)
+               tags.formal_args,t,_ = tools.get_parameters(tok,')',',',self)
             else
                tags.formal_args = List()
             end
-            t,v = tnext(tok)
+            t,_ = tnext(tok)
             tags:add('class','function')
-            if t == '>' then
+            if t ~= '>' then
---~                tags.formal_args:insert(1,'self')
---~                tags.formal_args.comments = {self=''}
-            else
                tags.static = true
             end
          end

ldoc/lexer.lua

@@ -171,7 +171,7 @@ function lexer.scan (s,matches,filter,options)
         end
         matches = plain_matches
     end
-    local i1,i2,idx,res1,res2,tok,pat,fun,capt
+    local i1,i2,tok,pat,fun
     local line = 1
     if file then
         s = file:read()

ldoc/markdown.lua

@@ -149,9 +149,6 @@ local function map(t, f)
 	return out
 end
 
--- The identity function, useful as a placeholder.
-local function identity(text) return text end
-
 -- Functional style if statement. (NOTE: no short circuit evaluation)
 local function iff(t, a, b) if t then return a else return b end end
 
@@ -641,12 +638,14 @@ local function blockquotes(lines)
 
 		local stop = #lines
 		for i = start+1, #lines do
+			-- luacheck: push ignore 542
 			if lines[i].type == "blank" or lines[i].type == "blockquote" then
 			elseif lines[i].type == "normal" then
 				if lines[i-1].type == "blank" then stop = i-1 break end
 			else
 				stop = i-1 break
 			end
+			-- luacheck: pop
 		end
 		while lines[stop].type == "blank" do stop = stop - 1 end
 		return start, stop
@@ -766,14 +765,6 @@ function block_transform(text, sublist)
 	return text
 end
 
--- Debug function for printing a line array to see the result
--- of partial transforms.
-local function print_lines(lines)
-	for i, line in ipairs(lines) do
-		print(i, line.type, line.text or line.line)
-	end
-end
-
 ----------------------------------------------------------------------
 -- Span transform
 ----------------------------------------------------------------------
@@ -880,7 +871,6 @@ local function code_spans(s)
 			pos = stop + 1
 		end
 	end
-	return s
 end
 
 -- Encode alt text... enodes &, and ".
@@ -1177,10 +1167,12 @@ function OptionParser:run(args)
 	while pos <= #args do
 		local arg = args[pos]
 		if arg == "--" then
+			-- luacheck: push ignore 512
 			for i=pos+1,#args do
 				if self.arg then self.arg(args[i]) end
 				return true
 			end
+			-- luacheck: pop
 		end
 		if arg:match("^%-%-") then
 			local info = self.long[arg:sub(3)]
@@ -1229,7 +1221,7 @@ local function run_command_line(arg)
 	local function run(s, options)
 		s = markdown(s)
 		if not options.wrap_header then return s end
-		local header = ""
+		local header
 		if options.header then
 			local f = io.open(options.header) or error("Could not open file: " .. options.header)
 			header = f:read("*a")

ldoc/markup.lua

@@ -7,7 +7,7 @@ local doc = require 'ldoc.doc'
 local utils = require 'pl.utils'
 local stringx = require 'pl.stringx'
 local prettify = require 'ldoc.prettify'
-local quit, concat, lstrip = utils.quit, table.concat, stringx.lstrip
+local concat = table.concat
 local markup = {}
 
 local backtick_references
@@ -53,7 +53,7 @@ local function resolve_inline_references (ldoc, txt, item, plain)
    end))
    if backtick_references then
       res  = res:gsub('`([^`]+)`',function(name)
-         local ref,err = markup.process_reference(name)
+         local ref,_ = markup.process_reference(name)
          local label = name
          if name and do_escape then
             label = name:gsub('_', '\\_')
@@ -135,10 +135,10 @@ local function process_multiline_markdown(ldoc, txt, F, filename, deflang)
    local function pretty_code (code, lang)
       code = concat(code,'\n')
       if code ~= '' then
-         local err
+         local _
          -- If we omit the following '\n', a '--' (or '//') comment on the
          -- last line won't be recognized.
-         code, err = prettify.code(lang,filename,code..'\n',L,false)
+         code, _ = prettify.code(lang,filename,code..'\n',L,false)
          code = resolve_inline_references(ldoc, code, err_item,true)
          append(res,'<pre>')
          append(res, code)
@@ -237,6 +237,7 @@ local formatters =
    discount = function(format)
       local ok, markdown = pcall(require, 'discount')
       if ok then
+         -- luacheck: push ignore 542
          if 'function' == type(markdown) then
             -- lua-discount by A.S. Bradbury, https://luarocks.org/modules/luarocks/lua-discount
          elseif 'table' == type(markdown) and ('function' == type(markdown.compile) or 'function' == type(markdown.to_html)) then
@@ -254,12 +255,13 @@ local formatters =
                   end
                else
                   io.stderr:write('LDoc discount failed with error ',errmsg)
-                  io.exit(1)
+                  os.exit(1)
                end
             end
          else
             ok = false
          end
+         -- luacheck: pop
       end
       if not ok then
          print('format: using built-in markdown')

ldoc/parse.lua

@@ -2,7 +2,7 @@
 
 local utils = require 'pl.utils'
 local List = require 'pl.List'
-local Map = require 'pl.Map'
+-- local Map = require 'pl.Map'
 local stringio = require 'pl.stringio'
 local lexer = require 'ldoc.lexer'
 local tools = require 'ldoc.tools'
@@ -161,12 +161,6 @@ local function extract_tags (s,args)
    return tags --Map(tags)
 end
 
-local _xpcall = xpcall
-if true then
-   _xpcall = function(f) return true, f() end
-end
-
-
 
 -- parses a Lua or C file, looking for ldoc comments. These are like LuaDoc comments;
 -- they start with multiple '-'. (Block commments are allowed)
@@ -176,7 +170,6 @@ end
 -- module if there isn't an explicit module name specified.
 
 local function parse_file(fname, lang, package, args)
-   local line,f = 1
    local F = File(fname)
    local module_found, first_comment = false,true
    local current_item, module_item
@@ -192,10 +185,7 @@ local function parse_file(fname, lang, package, args)
       return tok:lineno()
    end
 
-   local function filename () return fname end
-
    function F:warning (msg,kind,line)
-      kind = kind or 'warning'
       line = line or lineno()
       Item.had_warning = true
       io.stderr:write(fname..':'..line..': '..msg,'\n')
@@ -307,7 +297,7 @@ local function parse_file(fname, lang, package, args)
                   module_found = tags.name
                   -- might be a module returning a single function!
                   if tags.param or tags['return'] then
-                     local parms, ret, summ = tags.param, tags['return'],tags.summary
+                     local parms, ret = tags.param, tags['return']
                      local name = tags.name
                      tags.param = nil
                      tags['return'] = nil

ldoc/prettify.lua

@@ -30,8 +30,8 @@ local spans = {keyword=true,number=true,string=true,comment=true,global=true,bac
 local cpp_lang = {C = true, c = true, cpp = true, cxx = true, h = true}
 
 function prettify.lua (lang, fname, code, initial_lineno, pre, linenos)
-   local res, lexer, tokenizer = List(), require 'ldoc.lexer'
+   local res, lexer = List(), require 'ldoc.lexer'
-   local tnext = lexer.skipws
+   local tokenizer
    local ik = 1
    if not cpp_lang[lang] then
       tokenizer = lexer.lua

ldoc/tools.lua

@@ -79,7 +79,7 @@ end
 
 function KindMap:put_kind_first (kind)
    -- find this kind in our kind list
-   local kinds = self.klass.kinds,kind
+   local kinds = self.klass.kinds
    local idx = tablex.find(kinds,kind)
    -- and swop with the start!
    if idx then
@@ -232,8 +232,9 @@ end
 function M.check_file (f,original)
    if not path.exists(f) or path.getmtime(original) > path.getmtime(f) then
       local text,err = utils.readfile(original)
+      local _
       if text then
-         text,err = utils.writefile(f,text)
+         _,err = utils.writefile(f,text)
       end
       if err then
          quit("Could not copy "..original.." to "..f)
@@ -250,13 +251,12 @@ function M.writefile(name,text)
 end
 
 function M.name_of (lpath)
-   local ext
+   local _
-   lpath,ext = path.splitext(lpath)
+   lpath,_ = path.splitext(lpath)
    return lpath
 end
 
 function M.this_module_name (basename,fname)
-   local ext
    if basename == '' then
       return M.name_of(fname)
    end
@@ -429,7 +429,7 @@ end
 -- Set `colon` to be the secondary separator, '' for none.
 function M.get_fun_name (tok,first,colon)
    local res = {}
-   local t,name,sep
+   local t,name,sep,_
    colon = colon or ':'
    if not first then
       t,name = tnext(tok)
@@ -441,7 +441,7 @@ function M.get_fun_name (tok,first,colon)
    while sep == '.' or sep == colon do
       append(res,name)
       append(res,sep)
-      t,name = tnext(tok)
+      _,name = tnext(tok)
       t,sep = tnext(tok)
    end
    append(res,name)

run-tests.lua

@@ -1,13 +1,15 @@
+local PWD = os.getenv("PWD")
+
 local run
 if not arg[1] then
   run = function (dir)
-     local cmd = 'cd '..dir..' && ldoc --testing . && diff -r doc cdocs'
+     local cmd = 'cd '..dir..' && lua '..PWD..'/ldoc.lua --testing . && diff -r doc cdocs'
      print(cmd)
      os.execute(cmd)
   end
 elseif arg[1] == 'update' then
    run = function (dir)
-     local cmd = 'cd '..dir..' && ldoc --dir cdocs --testing .'
+     local cmd = 'cd '..dir..' && lua '..PWD..'/ldoc.lua --dir cdocs --testing .'
      print(cmd)
      os.execute(cmd)
    end