docs: clarify config file watch semantics (#429)

Fix for https://github.com/envoyproxy/envoy/issues/2241

Signed-off-by: Matt Klein <mklein@lyft.com>

api/config_source.proto

@@ -69,6 +69,12 @@ message ConfigSource {
     // .. note::
     //
     //  The path to the source must exist at config load time.
+    //
+    // .. note::
+    //
+    //   Envoy will only watch the file path for *moves.* This is because in general only moves
+    //   are atomic. The same method of swapping files as is demonstrated in the
+    //   :ref:`runtime documentation <config_runtime_symbolic_link_swap>` can be used here also.
     string path = 1;
     // API configuration source.
     ApiConfigSource api_config_source = 2;

docs/root/configuration/runtime.rst

@@ -55,6 +55,8 @@ Lines starting with ``#`` as the first character are treated as comments.
 Comments can be used to provide context on an existing value. Comments are also useful in an
 otherwise empty file to keep a placeholder for deployment in a time of need.
 
+.. _config_runtime_symbolic_link_swap:
+
 Updating runtime values via symbolic link swap
 ----------------------------------------------