stubtest: improve allowlist documentation (#15008)

Could help with e.g. matplotlib/matplotlib#24976

Author: hauntsaninja

docs/source/stubtest.rst

@@ -122,14 +122,29 @@ The rest of this section documents the command line interface of stubtest.
     allowlists. Allowlists can be created with --generate-allowlist. Allowlists
     support regular expressions.
 
+    The presence of an entry in the allowlist means stubtest will not generate
+    any errors for the corresponding definition.
+
 .. option:: --generate-allowlist
 
     Print an allowlist (to stdout) to be used with --allowlist
 
+    When introducing stubtest to an existing project, this is an easy way to
+    silence all existing errors.
+
 .. option:: --ignore-unused-allowlist
 
     Ignore unused allowlist entries
 
+    Without this option enabled, the default is for stubtest to complain if an
+    allowlist entry is not necessary for stubtest to pass successfully.
+
+    Note if an allowlist entry is a regex that matches the empty string,
+    stubtest will never consider it unused. For example, to get
+    `--ignore-unused-allowlist` behaviour for a single allowlist entry like
+    ``foo.bar`` you could add an allowlist entry ``(foo\.bar)?``.
+    This can be useful when an error only occurs on a specific platform.
+
 .. option:: --mypy-config-file FILE
 
     Use specified mypy config file to determine mypy plugins and mypy path