Merge remote-tracking branch 'upstream/master'

5 files changed, 100 insertions, 22 deletions

diff --git a/doc/ale-c.txt b/doc/ale-c.txt
index fe28cf4a..b0d94b8e 100644
--- a/doc/ale-c.txt
+++ b/doc/ale-c.txt
@@ -8,6 +8,17 @@ runs either `clang`, or `gcc`. See |ale-c-cc|.
 ===============================================================================
 Global Options
 
+g:ale_c_always_make                                       *g:ale_c_always_make*
+                                                          *b:ale_c_always_make*
+  Type: |Number|
+  Default: `has('unix') && !has('macunix')`
+
+  If set to `1`, use `--always-make` for `make`, which means that output will
+  always be parsed from `make` dry runs with GNU make. BSD `make` does not
+  support this option, so you probably want to turn this option off when using
+  a BSD variant.
+
+
 g:ale_c_build_dir_names                               *g:ale_c_build_dir_names*
                                                       *b:ale_c_build_dir_names*
 
@@ -58,6 +69,11 @@ g:ale_c_parse_makefile                                 *g:ale_c_parse_makefile*
   set for C or C++ compilers. This can make it easier to determine the correct
   build flags to use for different files.
 
+  NOTE: When using this option on BSD, you may need to set
+  |g:ale_c_always_make| to `0`, and `make -n` will not provide consistent
+  results if binaries have already been built, so use `make clean` when
+  editing your files.
+
   WARNING: Running `make -n` automatically can execute arbitrary code, even
   though it's supposed to be a dry run, so enable this option with care. You
   might prefer to use the buffer-local version of the option instead with
diff --git a/doc/ale-cpp.txt b/doc/ale-cpp.txt
index 651b4160..17894e6e 100644
--- a/doc/ale-cpp.txt
+++ b/doc/ale-cpp.txt
@@ -10,6 +10,7 @@ Global Options
 
 The following C options also apply to some C++ linters too.
 
+* |g:ale_c_always_make|
 * |g:ale_c_build_dir_names|
 * |g:ale_c_build_dir|
 * |g:ale_c_parse_makefile|
diff --git a/doc/ale-php.txt b/doc/ale-php.txt
index 645decd7..9fe868f8 100644
--- a/doc/ale-php.txt
+++ b/doc/ale-php.txt
@@ -189,42 +189,55 @@ g:ale_php_psalm_executable                         *g:ale_php_psalm_executable*
 
   This variable sets the executable used for psalm.
 
-g:ale_psalm_langserver_options                 *g:ale_psalm_langserver_options*
-                                               *b:ale_psalm_langserver_options*
+
+g:ale_php_psalm_options                               *g:ale_php_psalm_options*
+                                                      *b:ale_php_psalm_options*
   Type: |String|
   Default: `''`
 
   This variable can be set to pass additional options to psalm.
 
+
+g:ale_php_psalm_use_global                         *g:ale_php_psalm_use_global*
+                                                   *b:ale_php_psalm_use_global*
+  Type: |Boolean|
+  Default: `get(g:, 'ale_use_global_executables', 0)`
+
+  See |ale-integrations-local-executables|
+
+
 ===============================================================================
-php-cs-fixer                                              *ale-php-php-cs-fixer*
+php-cs-fixer                                             *ale-php-php-cs-fixer*
 
-g:ale_php_cs_fixer_executable                    *g:ale_php_cs_fixer_executable*
-                                                 *b:ale_php_cs_fixer_executable*
+g:ale_php_cs_fixer_executable                   *g:ale_php_cs_fixer_executable*
+                                                *b:ale_php_cs_fixer_executable*
   Type: |String|
   Default: `'php-cs-fixer'`
 
   This variable sets executable used for php-cs-fixer.
 
-g:ale_php_cs_fixer_use_global                    *g:ale_php_cs_fixer_use_global*
-                                                 *b:ale_php_cs_fixer_use_global*
-  Type: |Boolean|
-  Default: `get(g:, 'ale_use_global_executables', 0)`
-
-  This variable force globally installed fixer.
 
-g:ale_php_cs_fixer_options                          *g:ale_php_cs_fixer_options*
-                                                    *b:ale_php_cs_fixer_options*
+g:ale_php_cs_fixer_options                         *g:ale_php_cs_fixer_options*
+                                                   *b:ale_php_cs_fixer_options*
   Type: |String|
   Default: `''`
 
   This variable can be set to pass additional options to php-cs-fixer.
 
+
+g:ale_php_cs_fixer_use_global                   *g:ale_php_cs_fixer_use_global*
+                                                *b:ale_php_cs_fixer_use_global*
+  Type: |Boolean|
+  Default: `get(g:, 'ale_use_global_executables', 0)`
+
+  See |ale-integrations-local-executables|
+
+
 ===============================================================================
-php                                                                *ale-php-php*
+php                                                               *ale-php-php*
 
-g:ale_php_php_executable                              *g:ale_php_php_executable*
-                                                      *b:ale_php_php_executable*
+g:ale_php_php_executable                             *g:ale_php_php_executable*
+                                                     *b:ale_php_php_executable*
   Type: |String|
   Default: `'php'`
 
diff --git a/doc/ale-python.txt b/doc/ale-python.txt
index 60b0771d..6b1a6d33 100644
--- a/doc/ale-python.txt
+++ b/doc/ale-python.txt
@@ -169,13 +169,14 @@ flake8                                                      *ale-python-flake8*
 
 g:ale_python_flake8_change_directory     *g:ale_python_flake8_change_directory*
                                          *b:ale_python_flake8_change_directory*
-  Type: |Number|
-  Default: `1`
+  Type: |String|
+  Default: `project`
 
-  If set to `1`, ALE will switch to the directory the Python file being
-  checked with `flake8` is in before checking it. This helps `flake8` find
-  configuration files more easily. This option can be turned off if you want
-  to control the directory Python is executed from yourself.
+  If set to `project`, ALE will switch to the project root before checking file.
+  If set to `file`, ALE will switch to directory the Python file being
+  checked with `flake8` is in before checking it.
+  You can turn it off with `off` option if you want to control the directory
+  Python is executed from yourself.
 
 
 g:ale_python_flake8_executable                 *g:ale_python_flake8_executable*
diff --git a/doc/ale.txt b/doc/ale.txt
index f3b83df3..472c4852 100644
--- a/doc/ale.txt
+++ b/doc/ale.txt
@@ -463,12 +463,56 @@ is loaded. The delay for completion can be configured with
 |g:ale_completion_delay|. This setting should not be enabled if you wish to
 use ALE as a completion source for other plugins.
 
+ALE automatic completion will not work when 'paste' is active. Only set
+'paste' when you are copy and pasting text into your buffers.
+
+ALE automatic completion will interfere with default insert completion with
+`CTRL-N` and so on (|compl-vim|). You can write your own keybinds and a
+function in your |vimrc| file to force insert completion instead, like so: >
+
+  function! SmartInsertCompletion() abort
+    " Use the default CTRL-N in completion menus
+    if pumvisible()
+      return "\<C-n>"
+    endif
+
+    " Exit and re-enter insert mode, and use insert completion
+    return "\<C-c>a\<C-n>"
+  endfunction
+
+  inoremap <silent> <C-n> <C-R>=SmartInsertCompletion()<CR>
+<
 ALE provides an 'omnifunc' function |ale#completion#OmniFunc| for triggering
 completion manually with CTRL-X CTRL-O. |i_CTRL-X_CTRL-O| >
 
   " Use ALE's function for omnicompletion.
   set omnifunc=ale#completion#OmniFunc
 <
+                                                      *ale-completion-fallback*
+
+You can write your own completion function and fallback on other methods of
+completion by checking if there are no results that ALE can determine. For
+example, for Python code, you could fall back on the `python3complete`
+function. >
+
+  function! TestCompletionFunc(findstart, base) abort
+    let l:result = ale#completion#OmniFunc(a:findstart, a:base)
+
+    " Check if ALE couldn't find anything.
+    if (a:findstart && l:result is -3)
+    \|| (!a:findstart && empty(l:result))
+      " Defer to another omnifunc if ALE couldn't find anything.
+      return python3complete#Complete(a:findstart, a:base)
+    endif
+
+    return l:result
+  endfunction
+
+  set omnifunc=TestCompletionFunc
+<
+See |complete-functions| for documentation on how to write completion
+functions.
+
 ALE will only suggest so many possible matches for completion. The maximum
 number of items can be controlled with |g:ale_completion_max_suggestions|.
 
@@ -729,6 +773,9 @@ g:ale_completion_enabled                             *g:ale_completion_enabled*
   This setting should not be enabled if you wish to use ALE as a completion
   source for other completion plugins.
 
+  ALE automatic completion will not work when 'paste' is active. Only set
+  'paste' when you are copy and pasting text into your buffers.
+
   A buffer-local version of this setting `b:ale_completion_enabled` can be set
   to `0` to disable ALE's automatic completion support for a single buffer.
   ALE's completion support must be enabled globally to be enabled locally.