Improve help messages for global-related options

Author: mpeterv

docsrc/cli.rst

@@ -86,11 +86,11 @@ Option                                  Meaning
                                         * ``none`` - no standard globals.
 
                                         See :ref:`stds`
-``--globals [<global>] ...``            Add custom globals on top of standard ones.
-``--read-globals [<global>] ...``       Add read-only globals.
-``--new-globals [<global>] ...``        Set custom globals. Removes custom globals added previously.
-``--new-read-globals [<global>] ...``   Set read-only globals. Removes read-only globals added previously.
-``--not-globals [<global>] ...``        Remove custom and standard globals.
+``--globals [<name>] ...``              Add custom global variables or fields on top of standard ones. See :ref:`fields`
+``--read-globals [<name>] ...``         Add read-only global variables or fields.
+``--new-globals [<name>] ...``          Set custom global variables or fields. Removes custom globals added previously.
+``--new-read-globals [<name>] ...``     Set read-only global variables or fields. Removes read-only globals added previously.
+``--not-globals [<name>] ...``          Remove custom and standard global variables or fields.
 ``-c | --compat``                       Equivalent to ``--std max``.
 ``-d | --allow-defined``                Allow defining globals implicitly by setting them.
 
@@ -151,6 +151,8 @@ Pattern Matching warnings
 
 Unless already anchored, patterns matching variable names are anchored at both sides and patterns matching warning codes are anchored at their beginnings. This allows one to filter warnings by category (e.g. ``--only 1`` focuses ``luacheck`` on global-related warnings).
 
+.. _fields:
+
 Defining extra globals and fields
 ---------------------------------
 

src/luacheck/main.lua

@@ -81,36 +81,37 @@ together with used ones.]]):target("unused_secondaries"):action("store_false")
    none - no standard globals.
 
    Sets can be combined using "+".]]):format(default_std_name))
-      parser:option("--globals", "Add custom globals on top of standard ones.")
+      parser:option("--globals", [[Add custom global variables (e.g. foo) or
+fields (e.g. foo.bar) on top of standard ones.]])
          :args "*"
          :count "*"
-         :argname "<global>"
+         :argname "<name>"
          :action "concat"
          :init(nil)
-      parser:option("--read-globals", "Add read-only globals.")
+      parser:option("--read-globals", "Add read-only global variables or fields.")
          :args "*"
          :count "*"
-         :argname "<global>"
+         :argname "<name>"
          :action "concat"
          :init(nil)
-      parser:option("--new-globals", [[Set custom globals. Removes custom globals added
-previously.]])
+      parser:option("--new-globals", [[Set custom global variables or fields. Removes
+custom globals added previously.]])
          :args "*"
          :count "*"
-         :argname "<global>"
+         :argname "<name>"
          :action "concat"
          :init(nil)
-      parser:option("--new-read-globals", [[Set read-only globals. Removes read-only globals added
-previously.]])
+      parser:option("--new-read-globals", [[Set read-only global variables or fields. Removes
+read-only globals added previously.]])
          :args "*"
          :count "*"
-         :argname "<global>"
+         :argname "<name>"
          :action "concat"
          :init(nil)
-      parser:option("--not-globals", "Remove custom and standard globals.")
+      parser:option("--not-globals", "Remove custom and standard global variables or fields.")
          :args "*"
          :count "*"
-         :argname "<global>"
+         :argname "<name>"
          :action "concat"
          :init(nil)
       parser:flag("-c --compat", "Equivalent to --std max.")