Start updating docs

.gitignore

@@ -1,8 +1,4 @@
 bin/luacheck
-*.luac
-docsrc/_build
-docsrc/_static
-docsrc/_templates
 .luacheckcache
 luacov.stats.out
 luacov.report.out

doc/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: d43b93e13331a625eafd96b5503e6e76
+tags: 645f666f9bcd5a90fca523b33c5a78b7

doc/_sources/config.txt

@@ -1,9 +1,9 @@
 Configuration file
 ==================
 
-By default, ``luacheck`` tries to load configuration from ``.luacheckrc`` file in the current directory. Path to config can be set using ``--config`` option. Config loading can be disabled using ``--no-config`` flag.
+``luacheck`` tries to load configuration from ``.luacheckrc`` file in the current directory. If not found, it will look for it in the parent directory and so on, going up until it reaches file system root. Path to config can be set using ``--config`` option, in which case it will be used during recursive loading. Config loading can be disabled using ``--no-config`` flag.
 
-Config is simply a Lua script executed by ``luacheck``. It may set various options by assigning to globals.
+Config is simply a Lua script executed by ``luacheck``. It may set various options by assigning to globals or by returning a table with option names as keys.
 
 .. _options:
 
@@ -18,12 +18,15 @@ Option                 Type                                    Default value
 ``formatter``          String                                  ``"default"``
 ``cache``              Boolean or string                       ``false``
 ``jobs``               Positive integer                        ``1``
+``exclude_files``      Array of strings                        ``{}``
+``include_files``      Array of strings                        (Include all files)
 ``global``             Boolean                                 ``true``
 ``unused``             Boolean                                 ``true``
 ``redefined``          Boolean                                 ``true``
 ``unused_args``        Boolean                                 ``true``
 ``unused_secondaries`` Boolean                                 ``true``
-``std``                String or array of strings              ``"_G"``
+``self``               Boolean                                 ``true``
+``std``                String or set of standard globals       ``"_G"``
 ``globals``            Array of strings                        ``{}``
 ``new_globals``        Array of strings                        (Do not overwrite)
 ``read_globals``       Array of strings                        ``{}``
@@ -32,7 +35,6 @@ Option                 Type                                    Default value
 ``allow_defined``      Boolean                                 ``false``
 ``allow_defined_top``  Boolean                                 ``false``
 ``module``             Boolean                                 ``false``
-``unused_globals``     Boolean                                 ``true``
 ``ignore``             Array of patterns (see :ref:`patterns`) ``{}``
 ``enable``             Array of patterns                       ``{}``
 ``only``               Array of patterns                       (Do not filter)
@@ -45,39 +47,76 @@ An example of a config which makes ``luacheck`` ensure that only globals from th
    :linenos:
 
    std = "min"
-   ignore = {"211"}
+   ignore = {"212"}
 
-Per-prefix overrides
---------------------
+.. _custom_stds:
 
-The environment in which ``luacheck`` loads the config contains a special global ``files``. When checking a file ``<path>``, ``luacheck`` will override options from the main config with entries from ``files[<path_prefix>]``, applying entries for shorter prefixes first. This allows to override options for a specific file by setting ``files[<path>]``, and for all files in a directory by setting ``files[<dir>/]``. For example, the following config re-enables detection of unused arguments only for files in ``src/dir``, but not for ``src/dir/myfile.lua``:
+
+Custom sets of globals
+----------------------
+
+``std`` option allows setting a custom standard set of globals using a table. In that table, string keys are globals, and string in array part are read-only globals.
+
+Additionally, custom sets can be given names by mutating global ``stds`` variable. For example, when using `LPEG <http://www.inf.puc-rio.br/~roberto/lpeg/>`_ library, it makes sense to access its functions tersely using globals. In that case, the following config allows removing false positives related to global access easily:
+
+.. code-block:: lua
+   :linenos:
+
+   stds.lpeg = require "lpeg"
+
+.. code-block:: lua
+   :linenos:
+
+   local lpeg = require "lpeg"
+
+   local function parse1(...)
+      -- This function only uses lpeg functions as globals.
+      local _ENV = lpeg
+      -- luacheck: std lpeg
+      local digit, space = R "09", S " "
+      -- ...
+   end
+
+   local function parse2(...)
+      -- This function uses lpeg functions as well as standard globals.
+      local _ENV = setmetatable({}, {__index = function(_, k) return _ENV[k] or lpeg[k] end})
+      -- luacheck: std +lpeg
+      local digit, space = R "09", S " "
+      local number = C(digit^1) / tonumber
+      -- ...
+   end
+
+Per-file and per-path overrides
+-------------------------------
+
+The environment in which ``luacheck`` loads the config contains a special global ``files``. When checking a file ``<path>``, ``luacheck`` will override options from the main config with entries from ``files[<path>]`` and ``files[<parent_path>]``, applying entries for shorter paths first. For example, the following config re-enables detection of unused arguments only for files in ``src/dir``, but not for ``src/dir/myfile.lua``:
 
 .. code-block:: lua
    :linenos:
 
    std = "min"
-   ignore = {"211"}
+   ignore = {"212"}
 
-   files["src/dir/"] = {
-      enable = {"211"}
+   files["src/dir"] = {
+      enable = {"212"}
    }
 
    files["src/dir/myfile.lua"] = {
-      ignore = {"211"}
+      ignore = {"212"}
    }
 
 Note that ``files`` table supports autovivification, so that
 
 .. code-block:: lua
 
-   files["myfile.lua"].ignore = {"211"}
+   files["myfile.lua"].ignore = {"212"}
 
 and
 
 .. code-block:: lua
 
    files["myfile.lua"] = {
-      ignore = {"211"}
+      ignore = {"212"}
    }
 
 are equivalent.

doc/_sources/index.txt

@@ -11,4 +11,6 @@ Contents:
    inline
    module
 
-This is documentation for `Luacheck <https://github.com/mpeterv/luacheck/>`_ 0.10.0, a static analyzer and a linter for `Lua <http://www.lua.org/>`_.
+This is documentation for master branch version of `Luacheck <https://github.com/mpeterv/luacheck/>`_, a linter for `Lua <http://www.lua.org/>`_.
+
+This documentation is being updated.

doc/_sources/inline.txt

@@ -3,22 +3,30 @@ Inline options
 
 Luacheck supports setting some options directly in the checked files using inline configuration comments. An inline configuration comment starts with ``luacheck:`` label, possibly after some whitespace. The body of the comment should contain comma separated options, where option invocation consists of its name plus space separated arguments. The following options are supported:
 
-================= ============================================
-Option            Number of arguments
-================= ============================================
-compat            0
-module            0
-allow_defined     0
-allow_defined_top 0
-std               1
-globals           0+
-new_globals       0+
-read_globals      0+
-new_read_globals  0+
-ignore            0+ (without arguments everything is ignored)
-enable            1+
-only              1+
-================= ============================================
+================== ============================================
+Option             Number of arguments
+================== ============================================
+global             0
+unused             0
+redefined          0
+unused args        0
+unused secondaries 0
+self               0
+compat             0
+module             0
+allow defined      0
+allow defined top  0
+std                1
+globals            0+
+new globals        0+
+read globals       0+
+new read globals   0+
+ignore             0+ (without arguments everything is ignored)
+enable             1+
+only               1+
+================== ============================================
+
+Options that take no arguments can be prefixed with ``no`` to invert their meaning. E.g. ``--luacheck: no unused args`` disables unused argument warnings.
 
 Part of the file affected by inline option dependes on where it is placed. If there is any code on the line with the option, only that line is affected; otherwise, everthing till the end of the current closure is. In particular, inline options at the top of the file affect all of it:
 

doc/_sources/module.txt

@@ -3,9 +3,9 @@ Luacheck module
 
 Use ``local luacheck = require "luacheck"`` to import ``luacheck`` module. It contains the following functions:
 
-* ``luacheck.get_report(source)``: Given source string, returns analysis data (an array) or nil and syntax error table (table with fields ``line``, ``column``, ``offset``, ``msg``).
-* ``luacheck.process_reports(reports, options)``: Processes array of analysis reports and applies options. ``reports[i]`` uses ``options``, ``options[i]``, ``options[i][1]``, ``options[i][2]``, ... as options, overriding each other in that order. Options table is a table with fields similar to config options; see :ref:`options`. Analysis reports with field ``error`` are ignored. ``process_reports`` returns final report, see :ref:`report`.
-* ``luacheck.check_strings(sources, options)``: Checks array of sources using options, returns final report. Tables in ``sources`` array are ignored.
+* ``luacheck.get_report(source)``: Given source string, returns analysis data (a table).
+* ``luacheck.process_reports(reports, options)``: Processes array of analysis reports and applies options. ``reports[i]`` uses ``options``, ``options[i]``, ``options[i][1]``, ``options[i][2]``, ... as options, overriding each other in that order. Options table is a table with fields similar to config options; see :ref:`options`. Analysis reports with field ``fatal`` are ignored. ``process_reports`` returns final report, see :ref:`report`.
+* ``luacheck.check_strings(sources, options)``: Checks array of sources using options, returns final report. Tables with field ``fatal`` within ``sources`` array are ignored.
 * ``luacheck.check_files(files, options)``: Checks array of files using options, returns final report. Open file handles can passed instead of filenames, in which case they will be read till EOF and closed.
 
 ``luacheck._VERSION`` contains Luacheck version as a string in ``MAJOR.MINOR.PATCH`` format.
@@ -17,21 +17,19 @@ Using ``luacheck`` as a function is equivalent to calling ``luacheck.check_files
 Report format
 -------------
 
-A final report is an array of file reports plus fields ``warnings`` and ``errors`` containing total number of warnings and errors, correspondingly.
+A final report is an array of file reports plus fields ``warnings``, ``errors`` and ``fatals`` containing total number of warnings, errors and fatal errors, correspondingly.
 
-A file report is an array of warnings. If an error occured while checking a file, its report will have ``error`` field containing ``"I/O"`` or ``"syntax"``. In case of syntax error, ``line`` (number), ``colunmn`` (number), ``offset`` (number) and ``msg`` (string) fields are also present.
+A file report is an array of issues (warnings or errors). If a fatal error occured while checking a file, its report will have ``fatal`` field containing error type.
 
-A warning is a table with field ``code`` indicating the type of warning (see :doc:`warnings`), and fields ``line`` and ``column`` pointing to the source of the warning. Absence of ``code`` field indicates that the warning is related to a broken inline configuration comment; then, ``invalid`` field marks comments with invalid syntax, and ``unpaired`` field marks unpaired push/pop comments.
+An issue is a table with field ``code`` indicating its type (see :doc:`warnings`), and fields ``line``, ``column`` and ``end_column`` pointing to the source of the warning. ``name`` field may contain name of relate variable. Issues of some types can also have additional fields:
 
-Warnings of some types can also have additional fields:
-
-===== =======================================================================================
+===== ========================================================================================
 Codes Additional fields
-===== =======================================================================================
+===== ========================================================================================
+011   ``msg`` field contains syntax error message.
 111   ``module`` field indicates that assignment is to a non-module global variable.
 211   ``func`` field indicates that unused variable is a function.
-212   ``vararg`` field indicated that variable length argument is unused.
-4..   ``prev_line`` and ``prev_column`` fields contain location of the overwritten defintion.
-===== =======================================================================================
+4..   ``prev_line`` and ``prev_column`` fields contain location of the overwritten definition.
+===== ========================================================================================
 
 Other fields may be present for internal reasons.

doc/_sources/warnings.txt

@@ -1,11 +1,15 @@
 List of warnings
 ================
 
-Warnings produced by Luacheck are categorized using three-digit warning codes. Warning codes can be displayed in CLI output using ``--codes`` CLI option or ``code`` config option.
+Warnings produced by Luacheck are categorized using three-digit warning codes. Warning codes can be displayed in CLI output using ``--codes`` CLI option or ``codes`` config option. Errors also have codes starting with zero.
 
 ==== =============================================
 Code Description
 ==== =============================================
+011  A syntax error.
+021  An invalid inline option.
+022  An upaired inline push directive.
+023  An upaired inline pop directive.
 111  Setting an undefined global variable.
 112  Mutating an undefined global variable.
 113  Accessing an undefined global variable.