Address CR

python · ilevkivskyi · Nov 29, 2019 · Nov 28, 2019 · Nov 29, 2019 · Nov 29, 2019
commit 238edf44ceedd2be2e66b8e479d770af4b068b21
diff --git a/docs/source/mypy_daemon.rst b/docs/source/mypy_daemon.rst
@@ -99,46 +99,64 @@ Additional daemon flags
 
 .. option:: --status-file FILE
 
-   Status file to retrieve daemon details. This is normally a JSON file
-   that contains information about daemon process and connection. Default is
-   ``.dmypy.json``.
+   Use ``FILE`` as the status file for storing daemon runtime state. This is
+   normally a JSON file that contains information about daemon process and
+   connection. Default is ``.dmypy.json`` in current directory.
 
 .. option:: --log-file FILE
 
    Direct daemon stdout/stderr to ``FILE``. This is useful for debugging daemon
-   crashes, since the server traceback may be not printed to client stderr. Only
-   available for ``start``, ``restart``, and ``run`` commands.
+   crashes, since the server traceback may be not printed to client stderr.
+   Only available for ``start``, ``restart``, and ``run`` commands.
 
 .. option:: --timeout TIMEOUT
 
-   Server shutdown timeout (in seconds). Only available for ``start``,
-   ``restart``, and ``run`` commands.
+   Automatically shut down server after ``TIMEOUT`` seconds of inactivity.
+   Only available for ``start``, ``restart``, and ``run`` commands.
 
 .. option:: --fswatcher-dump-file FILE
 
    Collect information about the current file state. Only available for
-   ``status`` command.
+   ``status`` command. This will dump a JSON to ``FILE`` in the format
+   ``{path: [modification_time, size, content_hash]}``. This is useful for
+   debugging the built-in file system watcher. *Note:* this is an internal
+   flag and the format may change.
 
 .. option:: --perf-stats-file FILE
 
-   Write performance telemetry information to the given file. Only available
+   Write performance profiling information to ``FILE``. Only available
    for ``check``, ``recheck``, and ``run`` commands.
 
 .. option:: --update FILE
 
    Files in the run to add or check again, may be repeated. Default: all
    files from the previous run. Only available for ``recheck`` command.
+   This is useful when type checking thousands of files and using external
+   fast file system watcher, like `watchman`_ or `watchdog`_, to speed
+   things up. *Note:* this option is never required and is only available
+   for performance tuning.
 
 .. option:: --remove FILE
 
    Files to remove from the run, may be repeated. Only available for
-   ``recheck`` command.
+   ``recheck`` command. This flag an be used as an optimization to avoid
+   looking at all source files for deletions. *Note:* this option is never
+   required and is only available for performance tuning.
 
 Static inference of annotations
 *******************************
 
-Mypy daemon supports (as experimental feature) statically inferring draft type
-annotation for a given function or method. For example, given this program:
+Mypy daemon supports (as an experimental feature) statically inferring
+a draft type annotation for a given function or method. Running
+``dmypy suggest FUNCTION`` will produce a suggested signature in the format
+``(param_type_1, param_type_2, ...) -> ret_type`` (including named and
+star arguments).
+
+This low level command may be used by editors, IDEs, or similar tools, like
+`mypy plugin for PyCharm`_, to propose an annotation to user and/or to insert
+the annotation into a source file.
+
+In this example, the function ``format_id()`` has no annotation:
 
 .. code-block:: python
 
@@ -147,26 +165,34 @@ annotation for a given function or method. For example, given this program:
 
    root = format_id(0)
 
-Mypy can infer that ``format_id()`` takes an ``int`` and returns a ``str``.
-To get a suggested signature for a function, use ``dmypy suggest FUNCTION``,
-where the function may be specified in either of two forms:
+Mypy can use call sites and return statements (plus extra heuristics such as
+a signature in superclass for methods) to infer that ``format_id()`` takes
+an ``int`` and returns a ``str``. To get a suggested signature for a function,
+use ``dmypy suggest FUNCTION``, where the function may be specified in
+either of two forms:
 
 * By its fully qualified name, i.e. ``[package.]module.[class.]function``
 
-* By its textual location, i.e. ``/path/to/file.py:line``
-
-Running this command will produce a suggested signature in the format
-``(param_type_1, param_type_2, ...) -> ret_type``. This may be used by IDEs
-or similar tools to propose to user and/or insert the annotation into file.
+* By its textual location, i.e. ``/path/to/file.py:line``. The path can be
+  absolute or relative, and ``line`` can refer to any line number within
+  the function body.
 
 This command can also be used to find an improvement for an existing (imprecise)
 annotation. The following flags customize various aspects of the ``dmypy suggest``
 command.
 
 .. option:: --json
 
-   Use JSON format to output the signature, so that `PyAnnotate`_ can use it
-   to apply a suggestion to file.
+   Output the signature as JSON, so that `PyAnnotate`_ can use it to apply
+   a suggestion to file. An example JSON looks like this:
+
+   .. code-block:: python
+
+      [{"func_name": "example.format_id",
+        "line": 1,
+        "path": "/absolute/path/to/example.py",
+        "samples": 0,
+        "signature": {"arg_types": ["int"], "return_type": "str"}}]
 
 .. option:: --no-errors
 
@@ -197,7 +223,8 @@ command.
 .. option:: --use-fixme NAME
 
    A dummy name to use instead of plain ``Any`` for types that cannot
-   be inferred.
+   be inferred. This may be useful to emphasize to a user that a given type
+   can't be inferred and needs to be entered manually.
 
 .. option:: --max-guesses NUMBER
 
@@ -215,4 +242,7 @@ Limitations
   through the command line or through a
   :ref:`configuration file <config-file>`.
 
+.. _watchman: https://facebook.github.io/watchman/
+.. _watchdog: https://pypi.org/project/watchdog/
 .. _PyAnnotate: https://github.com/dropbox/pyannotate
+.. _mypy plugin for PyCharm: https://github.com/dropbox/mypy-PyCharm-plugin
diff --git a/mypy/dmypy/client.py b/mypy/dmypy/client.py
@@ -72,14 +72,14 @@ def __init__(self, prog: str) -> None:
 p.add_argument('-v', '--verbose', action='store_true', help="Print detailed status")
 p.add_argument('-q', '--quiet', action='store_true', help=argparse.SUPPRESS)  # Deprecated
 p.add_argument('--junit-xml', help="Write junit.xml to the given file")
-p.add_argument('--perf-stats-file', help='write telemetry information to the given file')
+p.add_argument('--perf-stats-file', help='write performance information to the given file')
 p.add_argument('files', metavar='FILE', nargs='+', help="File (or directory) to check")
 
 run_parser = p = subparsers.add_parser('run', formatter_class=AugmentedHelpFormatter,
                                        help="Check some files, [re]starting daemon if necessary")
 p.add_argument('-v', '--verbose', action='store_true', help="Print detailed status")
 p.add_argument('--junit-xml', help="Write junit.xml to the given file")
-p.add_argument('--perf-stats-file', help='write telemetry information to the given file')
+p.add_argument('--perf-stats-file', help='write performance information to the given file')
 p.add_argument('--timeout', metavar='TIMEOUT', type=int,
                help="Server shutdown timeout (in seconds)")
 p.add_argument('--log-file', metavar='FILE', type=str,
@@ -92,7 +92,7 @@ def __init__(self, prog: str) -> None:
 p.add_argument('-v', '--verbose', action='store_true', help="Print detailed status")
 p.add_argument('-q', '--quiet', action='store_true', help=argparse.SUPPRESS)  # Deprecated
 p.add_argument('--junit-xml', help="Write junit.xml to the given file")
-p.add_argument('--perf-stats-file', help='write telemetry information to the given file')
+p.add_argument('--perf-stats-file', help='write performance information to the given file')
 p.add_argument('--update', metavar='FILE', nargs='*',
                help="Files in the run to add or check again (default: all from previous run)")
 p.add_argument('--remove', metavar='FILE', nargs='*',