Linter: Amend docs for global_bear functionality

Add documentation on how to use @LINTER to create global
bears, both in the in-line documentation and in
Writing_Linter_Bears.rst.

Fixes coala#3968

coalib/bearlib/abstractions/Linter.py

@@ -659,8 +659,9 @@ def linter(executable: str,
            output_format: (str, None)=None,
            **options):
     """
-    Decorator that creates a ``LocalBear`` that is able to process results from
-    an external linter tool.
+    Decorator that creates a ``Bear`` that is able to process results from
+    an external linter tool. Depending on the value of ``global_bear`` this
+    can either be a ``LocalBear`` or a ``GlobalBear``.
 
     The main functionality is achieved through the ``create_arguments()``
     function that constructs the command-line-arguments that get passed to your
@@ -672,6 +673,17 @@ def linter(executable: str,
     ...     def create_arguments(filename, file, config_file):
     ...         return "--lint", filename
 
+    Or for a ``GlobalBear`` without the ``filename`` and ``file``:
+
+    >>> @linter("ylint",
+    ...         global_bear=True,
+    ...         output_format="regex",
+    ...         output_regex="...")
+    ... class YLintBear:
+    ...     @staticmethod
+    ...     def create_arguments(config_file):
+    ...         return "--lint", filename
+
     Requiring settings is possible like in ``Bear.run()`` with supplying
     additional keyword arguments (and if needed with defaults).
 
@@ -768,8 +780,7 @@ def linter(executable: str,
         provided together with ``prerequisite_check_command``.
     :param global_bear:
         Whether the created bear should be a ``GlobalBear`` or not. Global
-        bears will be run only once instead of once per file. The ``file``
-        and ``filename`` args of all their methods will default to ``None``.
+        bears will be run once on the whole project, instead of once per file.
         Incompatible with ``use_stdin=True``.
     :param output_format:
         The output format of the underlying executable. Valid values are

docs/Developers/Writing_Linter_Bears.rst

@@ -10,6 +10,12 @@ order to integrate linters in your bears.
   wrapping a tool, please refer to
   :doc:`this link instead<Writing_Native_Bears>`.
 
+  This tutorial takes you through the process of writing a local linter
+  Bear. If you want to write a global linter Bear, for a tool that does not
+  run once for each file, but only once for the whole project, you can still
+  go through the steps and then read about the differences of global linter
+  Bears at :ref:`global_bears`.
+
 Why is This Useful?
 -------------------
 
@@ -438,6 +444,36 @@ project.
 
 Congratulations!
 
+.. _global_bears:
+
+Global Linter Bears
+-------------------
+
+Some linting tools do not run on file level, i.e. once for each file, but on
+project level. They might check some properties of the directory structure or
+only check one specific file like the ``setup.py``.
+
+For these tools we need a ``GlobalBear`` and we can also use ``@linter`` to
+give us one, by passing the parameter ``global_bear=True``:
+
+::
+
+    from coalib.bearlib.abstractions.Linter import linter
+
+    @linter(executable='some_tool',
+            global_bear=True,
+            output_format='regex',
+            output_regex=r'<filename>: <message>'')
+    class SomeToolBear:
+        @staticmethod
+        def create_arguments(config_file):
+            pass
+
+The ``create_arguments`` method takes no ``filename`` and ``file`` in this case
+since there is no file context. You can still make coala aware of the file an
+issue was detected in, by using the ``filename`` named group in
+your ``output_regex`` if relevant to the wrapped tool.
+
 Where to Find More...
 ---------------------