Update README.md

More improvements.

README.md

@@ -18,16 +18,16 @@ For more information see the [Code of Conduct FAQ](https://opensource.microsoft.
 contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
 
 ## `ptvsd` CLI Usage
-### Debug a script file
-Use this to launch your script file. Launch script file without waiting for debugger to attach.
+### Debugging a script file
+To run a script file with debugging enabled, but without waiting for the debugger to attach (i.e. code starts executing immediately):
 ```console
 -m ptvsd --host localhost --port 5678 myfile.py
 ```
-If you want the debugger to attach before running your code use `--wait` flag.
+To wait until the debugger attaches before running your code, use the `--wait` switch.
 ```console
 -m ptvsd --host localhost  --port 5678 --wait myfile.py
 ```
-To attach from another machine, make sure that the server is listening on a public interface - using `0.0.0.0` will make it listen on all available interfaces:
+The `--host` option specifies the interface on which the debug server is listening for connections. To be able to attach from another machine, make sure that the server is listening on a public interface - using `0.0.0.0` will make it listen on all available interfaces:
 ```console
 -m ptvsd --host 0.0.0.0 --port 5678 myfile.py
 ```
@@ -35,53 +35,47 @@ This should only be done on secure networks, since anyone who can connect to the
 
 To pass arguments to the script, just specify them after the filename. This works the same as with Python itself - everything up to  the filename is processed by ptvsd, but everything after that becomes `sys.argv` of the running process.
 
-### Debug a module
-Use this to launch your module. Launch script file without waiting for debugger to attach.
+### Debugging a module
+To run a module, use the `-m` switch instead of filename:
 ```console
 -m ptvsd --host localhost --port 5678 -m mymodule
 ```
-If you want the debugger to attach before running your code use `--wait` flag.
-```console
--m ptvsd --host localhost --port 5678 --wait -m mymodule
-```
-Same as with scripts, command line arguments can be passed to the module by specifying them after the module name.
+Same as with scripts, command line arguments can be passed to the module by specifying them after the module name. All other ptvsd switches work identically in this mode; in particular, `--wait` can be used to block execution until debugger attaches.
 
-
-### Attach to a running process by ID
-Injects the debugger into a process with a given PID that is running Python code. Once this command returns, a ptvsd server is running within the process, as if it were launched via `-m ptvd` itself.
+### Attaching to a running process by ID
+The following command injects the debugger into a process with a given PID that is running Python code. Once the command returns, a ptvsd server is running within the process, as if that process was launched via `-m ptvsd` itself.
 ```console
 -m ptvsd --host localhost --port 5678 --pid 12345
 ```
 
 ## `ptvsd` Import usage
-### Enable debugging
-In your script import ptvsd and call `enable_attach` to enable the process to attach to the debugger. The default port is 5678. You can configure this while calling `enable_attach`. 
+### Enabling debugging
+At the beginning of your script, import ptvsd, and call `ptvsd.enable_attach()` to start the debug server. The default hostname is `0.0.0.0`, and the default port is 5678; these can be overridden by passing a `(host, port)` tuple as the first argument of `enable_attach()`. 
 ```python
 import ptvsd
 ptvsd.enable_attach()
-
-# your code
+...
 ```
-### Wait for attach
-Use the `wait_for_attach()` function to block execution until debugger is attached.
+
+### Waiting for debugger to attach
+Use the `ptvsd.wait_for_attach()` function to block program execution until debugger is attached.
 ```python
 import ptvsd
 ptvsd.enable_attach()
-ptvsd.wait_for_attach() # script execution will stop here till debugger is attached
-
-# your code
+ptvsd.wait_for_attach()  # blocks execution until debugger is attached
+...
 ```
 
 ### `breakpoint()` function
-In python >= 3.7, `ptvsd` supports the `breakpoint()` function. Use `break_into_debugger()` function for similar behavior and compatibility with older versions of python (2.7 and >= 3.4). These functions will block only if the debugger is attached.
+In Python 3.7 and above, `ptvsd` supports the standard `breakpoint()` function. Use `ptvsd.break_into_debugger()` function for similar behavior and compatibility with older versions of Python (3.6 and below). If the debugger is attached when either of these functions are invoked, it will pause execution on the calling line, as if it had a breakpoint set. If there's no debugger attached, the functions do nothing, and code continues to execute normally.
 ```python
 import ptvsd
 ptvsd.enable_attach()
 
 while True:
-    # your code
-    breakpoint() # ptvsd.break_into_debugger()
-    # your code
+    ...
+    breakpoint() # or ptvsd.break_into_debugger() on <3.7
+    ...
 ```
 
 ## Custom Protocol arguments