Tidy up some documentation

fix #880, fix #881

CHANGELOG.md

@@ -1,3 +1,9 @@
+Version 141:
+
+* Tidy up some documentation
+
+--------------------------------------------------------------------------------
+
 Version 140:
 
 * Fix some integer warnings in 64-bit builds

include/boost/beast/http/message.hpp

@@ -171,6 +171,11 @@ struct header<true, Fields> : Fields
 
     /** Returns the request-target string.
 
+        The request target string returned is the same string which
+        was received from the network or stored. In particular, it will
+        contain url-encoded characters and should follow the syntax
+        rules for URIs used with HTTP.
+
         @note This function is only available when `isRequest == true`.
     */
     string_view
@@ -178,6 +183,12 @@ struct header<true, Fields> : Fields
 
     /** Set the request-target string.
 
+        It is the caller's responsibility to ensure that the request
+        target string follows the syntax rules for URIs used with
+        HTTP. In particular, reserved or special characters must be
+        url-encoded. The implementation does not perform syntax checking
+        on the passed string.
+
         @param s A string representing the request-target.
 
         @note This function is only available when `isRequest == true`.

test/doc/exemplars.cpp

@@ -58,8 +58,6 @@ public:
     /** Construct the writer.
 
         @param msg The message whose body is to be serialized.
-
-        @param ec Set to the error, if any occurred.
     */
     template<bool isRequest, class Body, class Fields>
     explicit