Merge pull request #109 from Flow-IPC/polish

Comment and/or doc changes.

src/doc/manual/b-api_overview.dox.txt

@@ -291,6 +291,8 @@ All transport APIs at this layer, as well the structured layer (see below), have
 >     some_target_vector.resize(n_rcvd);
 >     // some_target_vector.begin()..end() = received blob.
 >     // fd.m_native_handle = `int` file descriptor/raw handle.
+>     // ...Deal with those inputs....
+>   }
 > });
 >
 > // In this case we create a Channel with 1 bidirectional pipe, a Unix domain socket stream, for both FDs and blobs.
@@ -623,12 +625,12 @@ Further capabilities are outside our scope here; but the main point is: At a min
 >   widgetHandle @7 :ShmHandle;
 > }
 > ~~~
-> 
+>
 > **Owner/lender** process transmitting such a message:
 > ~~~
 > auto x = session.session_shm()->construct<Widget>();
 > // ...Fill out *x as above....
-> 
+>
 > auto msg = cool_channel.create_msg();
 > // Ready the storage inside the out-message.
 > auto widget_handle_root = msg.body_root()->initSomeMsg().initWidgetHandle(); // Note `widgetHandle: ShmHandle` in schema.
@@ -637,12 +639,12 @@ Further capabilities are outside our scope here; but the main point is: At a min
 > // IPC-transmit it via struc::Channel.
 > cool_channel.send(msg);
 > ~~~
-> 
+>
 > **Borrower** process receiving such a message and accessing the native data structure `Widget`:
 > ~~~
 > flow::util::Blob_sans_log_context lend_blob;
 > shm::capnp_get_shm_handle_to_borrow(msg->body_root().getSomeMsg().getWidgetHandle(), &lend_blob);
-> 
+>
 > auto x = session.borrow_object<Widget>(lend_blob);
 > FLOW_LOG_INFO("Hey, let's read inside SHM after receiving SHM-handle: [" << x_borrowed->m_flag << "].");
 > // We can write to it too, in most cases.

src/doc/manual/h-safety_perms.dox.txt

@@ -35,7 +35,7 @@ You might note that the word we use here is **safety**, not *security*.  Of cour
       - In particular, if application A talks to B and C, and (say) SHared Memory is used all around, ideally the system should segregate vaddr (virtual address) areas in such a way as to make it impossible or at least unlikely that (due to an un-malicious user-code bug, maybe buffer overflow) data meant for B ends up being read by C.  (Customers might see that as *security*, but in our nomenclature it's about safety, since it's not an attack that caused the potential data breach but the vendor's own bug.)
     - If application B goes down, gracefully or especially ungracefully, application A should be wary of accessing resources shared (e.g., in SHared Memory -- SHM) with application B, and ideally it would know about the problem as soon as physically possible so as to limit the scope of damage in the meantime.
 
-This page is in no way a rigorous overview on how to maintain safety or how Flow-IPC is developed with it in mind.  (There may be such a document elsewhere.)  We merely wanted to point out that the specific features/APIs we are about to explain are targeting *safety* as opposed to security.  (For example an auth token is used by ipc::session, but it is not intentionally designed to be cryptographically strong, nor can it be revoked.  As another example: Akamai-API internals assume the opposing process is using genuine Akamai-API internals as well; the sky is the limit for possible damage, if that is not the case.)
+This page is in no way a rigorous overview on how to maintain safety or how Flow-IPC is developed with it in mind.  (There may be such a document elsewhere.)  We merely wanted to point out that the specific features/APIs we are about to explain are targeting *safety* as opposed to security.  (For example an auth token is used by ipc::session, but it is not intentionally designed to be cryptographically strong, nor can it be revoked.  As another example: Akamai-API internals assume the opposing process is using genuine Flow-IPC internals as well; the sky is the limit for possible damage, if that is not the case.)
 
 The described are a best effort aimed at safety, and as you make decisions about how to apply these APIs to your application(s), do keep in mind the idea is to keep code and data safe(r) from chaos as opposed to protect from malicious/unauthorized code.  If the latter is your concern, you must take your own additional measures.