Improvements to increase code coverage:

* Don't include the test code in coverage reports
* Add test code for missing coverage

Other:

* Improve the README.md
* Fix warning in sha1_context
* Tidy up the examples use of namespaces
* Various fixes to documentation and javadocs

test/http/read.cpp

@@ -7,3 +7,97 @@
 
 // Test that header file is self-contained.
 #include <beast/http/read.hpp>
+
+#include "../fail_stream.hpp"
+#include "../string_stream.hpp"
+#include "../yield_to.hpp"
+
+#include <beast/http/streambuf_body.hpp>
+#include <beast/detail/unit_test/suite.hpp>
+#include <boost/asio/spawn.hpp>
+
+namespace beast {
+namespace http {
+
+class read_test
+    : public beast::detail::unit_test::suite
+    , public test::enable_yield_to
+{
+public:
+    void testRead(yield_context do_yield)
+    {
+        static std::size_t constexpr limit = 100;
+        std::size_t n;
+        for(n = 1; n < limit; ++n)
+        {
+            streambuf sb;
+            test::fail_stream<test::string_stream> fs(n, ios_,
+                "GET / HTTP/1.1\r\n"
+                "Host: localhost\r\n"
+                "User-Agent: test\r\n"
+                "Content-Length: 0\r\n"
+                "\r\n"
+            );
+            request_v1<streambuf_body> m;
+            try
+            {
+                read(fs, sb, m);
+                break;
+            }
+            catch(std::exception const&)
+            {
+            }
+        }
+        expect(n < limit);
+        for(n = 1; n < limit; ++n)
+        {
+            streambuf sb;
+            test::fail_stream<test::string_stream> fs(n, ios_,
+                "GET / HTTP/1.1\r\n"
+                "Host: localhost\r\n"
+                "User-Agent: test\r\n"
+                "Content-Length: 0\r\n"
+                "\r\n"
+            );
+            request_v1<streambuf_body> m;
+            error_code ec;
+            read(fs, sb, m, ec);
+            if(! ec)
+                break;
+        }
+        expect(n < limit);
+        ios_.post(
+            [&]{
+                n = 1;
+            });
+        for(n = 1; n < limit; ++n)
+        {
+            streambuf sb;
+            test::fail_stream<test::string_stream> fs(n, ios_,
+                "GET / HTTP/1.1\r\n"
+                "Host: localhost\r\n"
+                "User-Agent: test\r\n"
+                "Content-Length: 0\r\n"
+                "\r\n"
+            );
+            request_v1<streambuf_body> m;
+            error_code ec;
+            async_read(fs, sb, m, do_yield[ec]);
+            if(! ec)
+                break;
+        }
+        expect(n < limit);
+    }
+
+    void run() override
+    {
+        yield_to(std::bind(&read_test::testRead,
+            this, std::placeholders::_1));
+    }
+};
+
+BEAST_DEFINE_TESTSUITE(read,http,beast);
+
+} // http
+} // beast
+