doc, tests: specify --headless

README.md

@@ -103,12 +103,17 @@ bridge](http://vimdoc.sourceforge.net/htmldoc/if_pyth.html#python-vim)):
 [1, 2, 3]
 ```
 
-You can embed neovim into your python application instead of binding to a
-running neovim instance.
+You can embed Neovim into your python application instead of connecting to
+a running Neovim instance.
 
 ```python
 >>> from pynvim import attach
->>> nvim = attach('child', argv=["/bin/env", "nvim", "--embed"])
+>>> nvim = attach('child', argv=["/bin/env", "nvim", "--embed", "--headless"])
 ```
 
-The tests can be consulted for more examples.
+- The ` --headless` argument tells `nvim` not to wait for a UI to connect.
+- Alternatively, use `--embed` _without_ `--headless` if your client is a UI
+  and you want `nvim` to wait for your client to `nvim_ui_attach` before
+  continuing startup.
+
+See the tests for more examples.

docs/development.rst

@@ -26,7 +26,7 @@ directory added to ``sys.path``.
 
 If you want to test a different version than ``nvim`` in ``$PATH`` use::
 
-    NVIM_CHILD_ARGV='["/path/to/nvim", "-u", "NONE", "--embed"]' pytest
+    NVIM_CHILD_ARGV='["/path/to/nvim", "-u", "NONE", "--embed", "--headless"]' pytest
 
 Alternatively, if you want to see the state of nvim, you could use::
 
@@ -86,6 +86,6 @@ You can embed Neovim into your python application instead of binding to a runnin
 .. code-block:: python
 
     >>> from pynvim import attach
-    >>> nvim = attach('child', argv=["/bin/env", "nvim", "--embed"])
+    >>> nvim = attach('child', argv=["/bin/env", "nvim", "--embed", "--headless"])
 
 The tests can be consulted for more examples.

pynvim/api/nvim.py

@@ -389,7 +389,10 @@ def replace_termcodes(self, string, from_part=False, do_lt=True,
                             from_part, do_lt, special)
 
     def out_write(self, msg, **kwargs):
-        """Print `msg` as a normal message."""
+        r"""Print `msg` as a normal message.
+
+        The message is buffered (won't display) until linefeed ("\n").
+        """
         return self.request('nvim_out_write', msg, **kwargs)
 
     def err_write(self, msg, **kwargs):

pynvim/msgpack_rpc/event_loop/base.py

@@ -33,7 +33,7 @@ class BaseEventLoop(object):
       named pipe.
     - `_connect_stdio()`: Use stdin/stdout as the connection to Nvim
     - `_connect_child(argv)`: Use the argument vector `argv` to spawn an
-      embedded Nvim that has it's stdin/stdout connected to the event loop.
+      embedded Nvim that has its stdin/stdout connected to the event loop.
     - `_start_reading()`: Called after any of _connect_* methods. Can be used
       to perform any post-connection setup or validation.
     - `_send(data)`: Send `data`(byte array) to Nvim. The data is only
@@ -70,7 +70,8 @@ def __init__(self, transport_type, *args):
         Traceback (most recent call last):
             ...
         AttributeError: 'BaseEventLoop' object has no attribute '_init'
-        >>> BaseEventLoop('child', ['nvim', '--embed', '-u', 'NONE'])
+        >>> BaseEventLoop('child',
+                ['nvim', '--embed', '--headless', '-u', 'NONE'])
         Traceback (most recent call last):
             ...
         AttributeError: 'BaseEventLoop' object has no attribute '_init'

test/conftest.py

@@ -57,7 +57,7 @@ def vim():
     child_argv = os.environ.get('NVIM_CHILD_ARGV')
     listen_address = os.environ.get('NVIM_LISTEN_ADDRESS')
     if child_argv is None and listen_address is None:
-        child_argv = '["nvim", "-u", "NONE", "--embed"]'
+        child_argv = '["nvim", "-u", "NONE", "--embed", "--headless"]'
 
     if child_argv is not None:
         editor = pynvim.attach('child', argv=json.loads(child_argv))