Documentation work

CHANGELOG.md

@@ -1,6 +1,7 @@
 Version 78:
 
 * Add span
+* Documentation work
 
 HTTP:
 

doc/1_intro.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section Introduction]
+[section:intro Introduction]
 
 Beast is a C++ header-only library serving as a foundation for writing
 interoperable networking libraries by providing [*low-level HTTP/1,

doc/2_examples.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section Quick Start]
+[section:quickstart Quick Start]
 [block'''<?dbhtml stop-chunking?>''']
 
 These complete programs are intended to quickly impress upon readers
@@ -36,7 +36,7 @@ File: [repo_file example/websocket-client/websocket_client.cpp]
 
 
 
-[section Examples]
+[section:examples Examples]
 [block'''<?dbhtml stop-chunking?>''']
 
 Source code and build scripts for these programs are located

doc/3_0_core.qbk

@@ -5,14 +5,14 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section Using Networking]
+[section:using_io Using I/O]
 
-This library makes network primitives used by the implementation publicly
+This library makes I/O primitives used by the implementation publicly
 available so users can take advantage of them in their own libraries.
-These primitives include traits, buffers, buffer algorithms, and helpers
+These primitives include traits, buffers, buffer algorithms, files,
-for implementing asynchronous operations compatible with __Asio__ and
+and helpers for implementing asynchronous operations compatible with
-described in __N3747__. This section lists these facilities by group,
+__Asio__ and described in __N3747__. This section lists these facilities
-with descriptions.
+by group, with descriptions.
 
 [important
     This documentation assumes familiarity with __Asio__. Sample
@@ -26,7 +26,8 @@ with descriptions.
 [include 3_1_asio.qbk]
 [include 3_2_streams.qbk]
 [include 3_3_buffers.qbk]
-[include 3_4_composed.qbk]
+[include 3_4_files.qbk]
-[include 3_5_detect_ssl.qbk]
+[include 3_5_composed.qbk]
+[include 3_6_detect_ssl.qbk]
 
 [endsect]

doc/3_4_files.qbk

@@ -0,0 +1,38 @@
+[/
+    Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:files Files]
+
+Often when implementing network algorithms such as servers, it is necessary
+to interact with files on the system. Beast defines the __File__ concept
+and several models to facilitate cross-platform interaction with the
+underlying filesystem:
+
+[table File Types
+[[Name][Description]]
+[[
+    [link beast.ref.beast__file_stdio `file_stdio`]
+][
+    This implementation of __File__ uses the C++ standard library
+    facilities obtained by including `<cstdio>`.
+]]
+[[
+    [link beast.ref.beast__file_win32 `file_win32`]
+][
+    This implements a __File__ for the Win32 API. It provides low level
+    access to the native file handle when necessary.
+]]
+[[
+    [link beast.ref.beast__file_posix `file_posix`]
+][
+    For POSIX systems, this class provides a suitable implementation
+    of __File__ which wraps the native file descriptor and provides
+    it if necessary.
+]]
+]
+
+[endsect]

doc/quickref.xml

@@ -178,6 +178,7 @@
             <member><link linkend="beast.ref.beast__error_code">error_code</link></member>
             <member><link linkend="beast.ref.beast__error_condition">error_condition</link></member>
             <member><link linkend="beast.ref.beast__file">file</link></member>
+            <member><link linkend="beast.ref.beast__file_mode">file_mode</link></member>
           </simplelist>
         </entry>
         <entry valign="top">

include/beast/http/write.hpp

@@ -44,9 +44,11 @@ namespace http {
     to the stream's `write_some` function.
 
     The amount of data actually transferred is controlled by the behavior
-    of the underlying stream, performing bounded work for each call. This
+    of the underlying stream, subject to the buffer size limit of the
-    helps applications set reasonable timeouts. It also allows application-level
+    serializer obtained or set through a call to @ref serializer::limit.
-    flow control to function correctly. For example when using a TCP/IP based
+    Setting a limit and performing bounded work helps applications set
+    reasonable timeouts. It also allows application-level flow control
+    to function correctly. For example when using a TCP/IP based
     stream.
 
     @param stream The stream to which the data is to be written.
@@ -80,9 +82,11 @@ write_some(SyncWriteStream& stream, serializer<
     to the stream's `write_some` function.
 
     The amount of data actually transferred is controlled by the behavior
-    of the underlying stream, performing bounded work for each call. This
+    of the underlying stream, subject to the buffer size limit of the
-    helps applications set reasonable timeouts. It also allows application-level
+    serializer obtained or set through a call to @ref serializer::limit.
-    flow control to function correctly. For example when using a TCP/IP based
+    Setting a limit and performing bounded work helps applications set
+    reasonable timeouts. It also allows application-level flow control
+    to function correctly. For example when using a TCP/IP based
     stream.
     
     @param stream The stream to which the data is to be written.
@@ -120,9 +124,11 @@ write_some(SyncWriteStream& stream, serializer<
     until this operation completes.
 
     The amount of data actually transferred is controlled by the behavior
-    of the underlying stream, performing bounded work for each call. This
+    of the underlying stream, subject to the buffer size limit of the
-    helps applications set reasonable timeouts. It also allows application-level
+    serializer obtained or set through a call to @ref serializer::limit.
-    flow control to function correctly. For example when using a TCP/IP based
+    Setting a limit and performing bounded work helps applications set
+    reasonable timeouts. It also allows application-level flow control
+    to function correctly. For example when using a TCP/IP based
     stream.
     
     @param stream The stream to which the data is to be written.