Update docs

mirage · Mar 19, 2015 · edee611 · edee611
1 parent ab7a7f5
commit edee611
Show file tree

Hide file tree

Showing 31 changed files with 632 additions and 488 deletions.
diff --git a/Mirage.html b/Mirage.html
@@ -604,10 +604,6 @@ <h2 id="2_Projectconfiguration">Project configuration</h2><br>
 <pre><span id="VALbuild"><span class="keyword">val</span> build</span> : <code class="type"><a href="Mirage.html#TYPEt">t</a> -> unit</code></pre><div class="info ">
 Call <code class="code">make build</code> in the right directory.<br>
 </div>
-
-<pre><span id="VALrun"><span class="keyword">val</span> run</span> : <code class="type"><a href="Mirage.html#TYPEt">t</a> -> unit</code></pre><div class="info ">
-call <code class="code">make run</code> in the right directory.<br>
-</div>
 <br>
 <h2 id="2_Extensions">Extensions</h2><br>
 

diff --git a/Mirage_misc.html b/Mirage_misc.html
@@ -78,7 +78,7 @@ <h2 id="2_Commandlineutilities">Command-line utilities</h2><br>
 <pre><span id="VALread_command"><span class="keyword">val</span> read_command</span> : <code class="type">('a, unit, string, string) Pervasives.format4 -> 'a</code></pre>
 <pre><span id="VALremove"><span class="keyword">val</span> remove</span> : <code class="type">string -> unit</code></pre>
 <pre><span id="VALrealpath"><span class="keyword">val</span> realpath</span> : <code class="type">string -> string</code></pre>
-<pre><span id="VALopam"><span class="keyword">val</span> opam</span> : <code class="type">string -> ?switch:string -> string list -> unit</code></pre>
+<pre><span id="VALopam"><span class="keyword">val</span> opam</span> : <code class="type">string -> ?yes:bool -> ?switch:string -> string list -> unit</code></pre>
 <pre><span id="VALin_dir"><span class="keyword">val</span> in_dir</span> : <code class="type">string -> (unit -> 'a) -> 'a</code></pre>
 <pre><span id="VALuname_s"><span class="keyword">val</span> uname_s</span> : <code class="type">unit -> string option</code></pre>
 <pre><span id="VALuname_m"><span class="keyword">val</span> uname_m</span> : <code class="type">unit -> string option</code></pre>

diff --git a/V1.BLOCK.html b/V1.BLOCK.html
@@ -14,7 +14,8 @@
 <link title="Mirage" rel="Chapter" href="Mirage.html">
 <link title="Mirage_misc" rel="Chapter" href="Mirage_misc.html">
 <link title="V1" rel="Chapter" href="V1.html">
-<link title="V1_LWT" rel="Chapter" href="V1_LWT.html"><title>V1.BLOCK</title>
+<link title="V1_LWT" rel="Chapter" href="V1_LWT.html"><link title="Sector-addressible block devices" rel="Section" href="#1_Sectoraddressibleblockdevices">
+<title>V1.BLOCK</title>
 </head>
 <body>
 <div class="navbar"><a class="pre" href="V1.CONSOLE.html" title="V1.CONSOLE">Previous</a>
@@ -25,18 +26,21 @@ <h1>Module type <a href="type_V1.BLOCK.html">V1.BLOCK</a></h1>
 
 <pre><span class="keyword">module type</span> BLOCK = <code class="code">sig</code> <a href="V1.BLOCK.html">..</a> <code class="code">end</code></pre><hr width="100%">
 <br>
-Operations on sector-addressible block devices, usually used
+<h1 id="1_Sectoraddressibleblockdevices">Sector-addressible block devices</h1>
+<p>
+
+      Operations on sector-addressible block devices, usually used
       for persistent storage<br>
 
 <pre><span id="TYPEpage_aligned_buffer"><span class="keyword">type</span> <code class="type"></code>page_aligned_buffer</span> </pre>
 <div class="info ">
-Abstract type for a page-aligned memory buffer<br>
+The type for page-aligned memory buffers.<br>
 </div>
 
 
 <pre><span id="TYPEerror"><span class="keyword">type</span> <code class="type"></code>error</span> = <code class="type">[ `Disconnected | `Is_read_only | `Unimplemented | `Unknown of string ]</code> </pre>
 <div class="info ">
-IO operation errors<br>
+The type for IO operation errors.<br>
 </div>
 
 
@@ -76,8 +80,8 @@ <h1>Module type <a href="type_V1.BLOCK.html">V1.BLOCK</a></h1>
 }
 
 <div class="info ">
-Characteristics of the block device. Note some devices may be able
-      to make themselves bigger over time.<br>
+Characteristics of the block device. Note some devices may be
+      able to make themselves bigger over time.<br>
 </div>
 
 
@@ -86,36 +90,45 @@ <h1>Module type <a href="type_V1.BLOCK.html">V1.BLOCK</a></h1>
 </div>
 
 <pre><span id="VALread"><span class="keyword">val</span> read</span> : <code class="type">t -><br>       int64 -><br>       <a href="V1.BLOCK.html#TYPEpage_aligned_buffer">page_aligned_buffer</a> list -><br>       [ `Error of <a href="V1.BLOCK.html#TYPEerror">error</a> | `Ok of unit ] io</code></pre><div class="info ">
-<code class="code">read device sector_start buffers</code> returns a blocking IO operation which
-      attempts to fill <code class="code">buffers</code> with data starting at <code class="code">sector_start</code>.
-      Each of <code class="code">buffers</code> must be a whole number of sectors in length. The list
-      of buffers can be of any length.<br>
+<code class="code">read device sector_start buffers</code> returns a blocking IO
+      operation which attempts to fill <code class="code">buffers</code> with data starting at
+      <code class="code">sector_start</code>.  Each of <code class="code">buffers</code> must be a whole number of
+      sectors in length. The list of buffers can be of any length.<br>
 </div>
 
 <pre><span id="VALwrite"><span class="keyword">val</span> write</span> : <code class="type">t -><br>       int64 -><br>       <a href="V1.BLOCK.html#TYPEpage_aligned_buffer">page_aligned_buffer</a> list -><br>       [ `Error of <a href="V1.BLOCK.html#TYPEerror">error</a> | `Ok of unit ] io</code></pre><div class="info ">
-<code class="code">write device sector_start buffers</code> returns a blocking IO operation which
-      attempts to write the data contained within <code class="code">buffers</code> to <code class="code">t</code> starting
-      at <code class="code">sector_start</code>. When the IO operation completes then all writes have been
-      persisted.
+<code class="code">write device sector_start buffers</code> returns a blocking IO
+      operation which attempts to write the data contained within
+      <code class="code">buffers</code> to <code class="code">t</code> starting at <code class="code">sector_start</code>. When the IO
+      operation completes then all writes have been persisted.
 <p>
 
-      Once submitted, it is not possible to cancel a request and there is no timeout.
+      Once submitted, it is not possible to cancel a request and there
+      is no timeout.
 <p>
 
-      The operation may fail with
-      * <code class="code">`Unimplemented</code>: the operation has not been implemented, no data has been written
-      * <code class="code">`Is_read_only</code>: the device is read-only, no data has been written
-      * <code class="code">`Disconnected</code>: the device has been disconnected at application request,
-        an unknown amount of data has been written
-      * <code class="code">`Unknown</code>: some other permanent, fatal error (e.g. disk is on fire), where
-        an unknown amount of data has been written
+      The operation may fail with:
+<p>
+
+      <ul>
+<li><code class="code">`Unimplemented</code>: the operation has not been implemented, no
+      data has been written.</li>
+<li><code class="code">`Is_read_only</code>: the device is read-only, no data has been
+      written.</li>
+<li><code class="code">`Disconnected</code>: the device has been disconnected at
+        application request, an unknown amount of data has been
+        written.</li>
+<li><code class="code">`Unknown</code>: some other permanent, fatal error (e.g. disk is
+        on fire), where an unknown amount of data has been written.</li>
+</ul>
+
 <p>
 
-      Each of <code class="code">buffers</code> must be a whole number of sectors in length. The list
-      of buffers can be of any length.
+      Each of <code class="code">buffers</code> must be a whole number of sectors in
+      length. The list of buffers can be of any length.
 <p>
 
-      The data will not be copied, so the supplied buffers must not be re-used
-      until the IO operation completes.<br>
+      The data will not be copied, so the supplied buffers must not be
+      re-used until the IO operation completes.<br>
 </div>
 </body></html>
diff --git a/V1.CHANNEL.html b/V1.CHANNEL.html
@@ -14,7 +14,8 @@
 <link title="Mirage" rel="Chapter" href="Mirage.html">
 <link title="Mirage_misc" rel="Chapter" href="Mirage_misc.html">
 <link title="V1" rel="Chapter" href="V1.html">
-<link title="V1_LWT" rel="Chapter" href="V1_LWT.html"><title>V1.CHANNEL</title>
+<link title="V1_LWT" rel="Chapter" href="V1_LWT.html"><link title="Buffered byte-stream" rel="Section" href="#1_Bufferedbytestream">
+<title>V1.CHANNEL</title>
 </head>
 <body>
 <div class="navbar"><a class="pre" href="V1.STACKV4.html" title="V1.STACKV4">Previous</a>
@@ -25,101 +26,117 @@ <h1>Module type <a href="type_V1.CHANNEL.html">V1.CHANNEL</a></h1>
 
 <pre><span class="keyword">module type</span> CHANNEL = <code class="code">sig</code> <a href="V1.CHANNEL.html">..</a> <code class="code">end</code></pre><hr width="100%">
 <br>
-Type of a buffered byte-stream that is attached to an unbuffered
+<h1 id="1_Bufferedbytestream">Buffered byte-stream</h1>
+<p>
+
+      Type of a buffered byte-stream that is attached to an unbuffered
       flow (e.g. a TCPv4 connection).<br>
 
 <pre><span id="TYPEbuffer"><span class="keyword">type</span> <code class="type"></code>buffer</span> </pre>
 <div class="info ">
-Abstract type for a memory buffer that may not be page aligned.<br>
+The type for memory buffers.<br>
 </div>
 
 
 <pre><span id="TYPEflow"><span class="keyword">type</span> <code class="type"></code>flow</span> </pre>
 <div class="info ">
-Abstract type for an unbuffered network flow.<br>
+The type for unbuffered network flow.<br>
 </div>
 
 
 <pre><span id="TYPEt"><span class="keyword">type</span> <code class="type"></code>t</span> </pre>
 <div class="info ">
-State associated with this channel, such as the inflight buffers.<br>
+The type for the state associated with channels, such as the
+      inflight buffers.<br>
 </div>
 
 
 <pre><span id="TYPEio"><span class="keyword">type</span> <code class="type">+'a</code> io</span> </pre>
 <div class="info ">
-Abstract type of a blocking IO monad.<br>
+The type for potentially blocking I/O operation<br>
 </div>
 
 
 <pre><span id="TYPEio_stream"><span class="keyword">type</span> <code class="type">'a</code> io_stream</span> </pre>
 <div class="info ">
-Abstract type of a blocking stream of IO requests.<br>
+The type for potentially blocking stream of IO requests.<br>
 </div>
 
 
 <pre><span id="VALcreate"><span class="keyword">val</span> create</span> : <code class="type"><a href="V1.CHANNEL.html#TYPEflow">flow</a> -> <a href="V1.CHANNEL.html#TYPEt">t</a></code></pre><div class="info ">
-<code class="code">create flow</code> will allocate send and receive buffers and associated them
-      with the given unbuffered <code class="code">flow</code>.<br>
+<code class="code">create flow</code> will allocate send and receive buffers and
+      associated them with the given unbuffered <code class="code">flow</code>.<br>
 </div>
 
 <pre><span id="VALto_flow"><span class="keyword">val</span> to_flow</span> : <code class="type"><a href="V1.CHANNEL.html#TYPEt">t</a> -> <a href="V1.CHANNEL.html#TYPEflow">flow</a></code></pre><div class="info ">
 <code class="code">to_flow t</code> will return the flow that backs this channel.<br>
 </div>
 
 <pre><span id="VALread_char"><span class="keyword">val</span> read_char</span> : <code class="type"><a href="V1.CHANNEL.html#TYPEt">t</a> -> char <a href="V1.CHANNEL.html#TYPEio">io</a></code></pre><div class="info ">
-Read a single character from the channel, blocking if there is no immediately
-      available input data.<br>
+Read a single character from the channel, blocking if there is
+      no immediately available input data.<br>
 </div>
 
 <pre><span id="VALread_until"><span class="keyword">val</span> read_until</span> : <code class="type"><a href="V1.CHANNEL.html#TYPEt">t</a> -> char -> (bool * <a href="V1.CHANNEL.html#TYPEbuffer">buffer</a>) <a href="V1.CHANNEL.html#TYPEio">io</a></code></pre><div class="info ">
-<code class="code">read_until t ch</code> will read from the channel until the given <code class="code">ch</code> character
-      is found.  It returns a tuple indicating whether the character was found at
-      all (<code class="code">false</code> indicates that an EOF condition occurred before the character
-      was encountered), and the <code class="code">buffer</code> pointing to the position immediately
-      after the character (or the complete scanned buffer if the character was
+<code class="code">read_until t ch</code> will read from the channel until the given
+      <code class="code">ch</code> character is found.  It returns a tuple indicating whether
+      the character was found at all (<code class="code">false</code> indicates that an EOF
+      condition occurred before the character was encountered), and
+      the <code class="code">buffer</code> pointing to the position immediately after the
+      character (or the complete scanned buffer if the character was
       never encountered).<br>
 </div>
 
-<pre><span id="VALread_some"><span class="keyword">val</span> read_some</span> : <code class="type">?len:int -> <a href="V1.CHANNEL.html#TYPEt">t</a> -> <a href="V1.CHANNEL.html#TYPEbuffer">buffer</a> <a href="V1.CHANNEL.html#TYPEio">io</a></code></pre>
+<pre><span id="VALread_some"><span class="keyword">val</span> read_some</span> : <code class="type">?len:int -> <a href="V1.CHANNEL.html#TYPEt">t</a> -> <a href="V1.CHANNEL.html#TYPEbuffer">buffer</a> <a href="V1.CHANNEL.html#TYPEio">io</a></code></pre><div class="info ">
+<code class="code">read_some ?len t</code> will read up to <code class="code">len</code> characters from the
+      input channel and at most a full <code class="code">buffer</code>. If <code class="code">len</code> is not
+      specified, it will read all available data and return that
+      buffer.<br>
+</div>
+
 <pre><span id="VALread_stream"><span class="keyword">val</span> read_stream</span> : <code class="type">?len:int -> <a href="V1.CHANNEL.html#TYPEt">t</a> -> <a href="V1.CHANNEL.html#TYPEbuffer">buffer</a> <a href="V1.CHANNEL.html#TYPEio_stream">io_stream</a></code></pre><div class="info ">
-<code class="code">read_stream ?len t</code> will return up to <code class="code">len</code> characters as a stream of
-     buffers. This call will probably be removed in a future revision of the API
-     in favour of <a href="V1.CHANNEL.html#VALread_some"><code class="code">V1.CHANNEL.read_some</code></a>.<br>
+<code class="code">read_stream ?len t</code> will return up to <code class="code">len</code> characters as a
+      stream of buffers. This call will probably be removed in a
+      future revision of the API in favour of <a href="V1.CHANNEL.html#VALread_some"><code class="code">V1.CHANNEL.read_some</code></a>.<br>
 </div>
 
 <pre><span id="VALread_line"><span class="keyword">val</span> read_line</span> : <code class="type"><a href="V1.CHANNEL.html#TYPEt">t</a> -> <a href="V1.CHANNEL.html#TYPEbuffer">buffer</a> list <a href="V1.CHANNEL.html#TYPEio">io</a></code></pre><div class="info ">
-<code class="code">read_line t</code> will read a line of input, which is terminated either by
-     a CRLF sequence, or the end of the channel (which counts as a line).<br>
-<b>Returns</b> Returns a list of views that terminates at EOF.<br>
+<code class="code">read_line t</code> will read a line of input, which is terminated
+      either by a CRLF sequence, or the end of the channel (which
+      counts as a line).<br>
+<b>Returns</b> Returns a list of views that
+      terminates at EOF.<br>
 </div>
 
 <pre><span id="VALwrite_char"><span class="keyword">val</span> write_char</span> : <code class="type"><a href="V1.CHANNEL.html#TYPEt">t</a> -> char -> unit</code></pre><div class="info ">
-<code class="code">write_char t ch</code> writes a single character to the output channel.<br>
+<code class="code">write_char t ch</code> writes a single character to the output
+      channel.<br>
 </div>
 
 <pre><span id="VALwrite_string"><span class="keyword">val</span> write_string</span> : <code class="type"><a href="V1.CHANNEL.html#TYPEt">t</a> -> string -> int -> int -> unit</code></pre><div class="info ">
-<code class="code">write_string t buf off len</code> writes <code class="code">len</code> bytes from a string <code class="code">buf</code>,
-     starting from from offset <code class="code">off</code>.<br>
+<code class="code">write_string t buf off len</code> writes <code class="code">len</code> bytes from a string
+      <code class="code">buf</code>, starting from from offset <code class="code">off</code>.<br>
 </div>
 
 <pre><span id="VALwrite_buffer"><span class="keyword">val</span> write_buffer</span> : <code class="type"><a href="V1.CHANNEL.html#TYPEt">t</a> -> <a href="V1.CHANNEL.html#TYPEbuffer">buffer</a> -> unit</code></pre><div class="info ">
-<code class="code">write_buffer t buf</code> will copy the buffer to the channel's output buffer.
-     The buffer should not be modified after being written, and it will be
-     recycled into the buffer allocation pool at some future point.<br>
+<code class="code">write_buffer t buf</code> will copy the buffer to the channel's
+      output buffer.  The buffer should not be modified after being
+      written, and it will be recycled into the buffer allocation pool
+      at some future point.<br>
 </div>
 
 <pre><span id="VALwrite_line"><span class="keyword">val</span> write_line</span> : <code class="type"><a href="V1.CHANNEL.html#TYPEt">t</a> -> string -> unit</code></pre><div class="info ">
-<code class="code">write_line t buf</code> will write the string <code class="code">buf</code> to the output channel
-     and append a newline character afterwards.<br>
+<code class="code">write_line t buf</code> will write the string <code class="code">buf</code> to the output
+      channel and append a newline character afterwards.<br>
 </div>
 
 <pre><span id="VALflush"><span class="keyword">val</span> flush</span> : <code class="type"><a href="V1.CHANNEL.html#TYPEt">t</a> -> unit <a href="V1.CHANNEL.html#TYPEio">io</a></code></pre><div class="info ">
-<code class="code">flush t</code> will flush the output buffer and block if necessary until it
-     is all written out to the flow.<br>
+<code class="code">flush t</code> will flush the output buffer and block if necessary
+      until it is all written out to the flow.<br>
 </div>
 
 <pre><span id="VALclose"><span class="keyword">val</span> close</span> : <code class="type"><a href="V1.CHANNEL.html#TYPEt">t</a> -> unit <a href="V1.CHANNEL.html#TYPEio">io</a></code></pre><div class="info ">
-<code class="code">close t</code> will call <a href="V1.CHANNEL.html#VALflush"><code class="code">V1.CHANNEL.flush</code></a> and then close the underlying flow.<br>
+<code class="code">close t</code> will call <a href="V1.CHANNEL.html#VALflush"><code class="code">V1.CHANNEL.flush</code></a> and then close the underlying
+      flow.<br>
 </div>
 </body></html>