Javadoc tidying

CHANGELOG.md

@@ -1,3 +1,9 @@
+Version 80:
+
+* Javadoc tidying
+
+--------------------------------------------------------------------------------
+
 Version 79:
 
 * Remove spurious fallthrough guidance

doc/5_02_message.qbk

@@ -161,9 +161,9 @@ meet the requirements, or use the ones that come with the library:
     Messages with this body type may be serialized and parsed.
 ]]
 [[
-    [link beast.ref.beast__http__basic_string_body `basic_string_body`]
-
     [link beast.ref.beast__http__string_body `string_body`]
+
+    [link beast.ref.beast__http__basic_string_body `basic_string_body`]
 ][
     A body whose `value_type` is `std::basic_string` or `std::string`.
     Insertion complexity is amortized constant time, while capacity

include/beast/core/buffer_cat.hpp

@@ -21,12 +21,6 @@ namespace beast {
 template<class... Buffers>
 class buffer_cat_view
 {
-#if 0
-    static_assert(
-        detail::is_all_const_buffer_sequence<Buffers...>::value,
-            "BufferSequence requirements not met");
-#endif
-
     std::tuple<Buffers...> bn_;
 
 public:
@@ -36,26 +30,23 @@ public:
         then `value_type` will be `boost::asio::mutable_buffer`.
         Otherwise, `value_type` will be `boost::asio::const_buffer`.
     */
-    using value_type =
+#if BEAST_DOXYGEN
-    #if BEAST_DOXYGEN
+    using value_type = implementation_defined;
-        implementation_defined;
+#else
-    #else
+    using value_type = typename
-        typename detail::common_buffers_type<Buffers...>::type;
+        detail::common_buffers_type<Buffers...>::type;
-    #endif
+#endif
 
     /// The type of iterator used by the concatenated sequence
     class const_iterator;
 
-    /// Move constructor
+    /// Constructor
     buffer_cat_view(buffer_cat_view&&) = default;
 
-    /// Copy constructor
+    /// Assignment
-    buffer_cat_view(buffer_cat_view const&) = default;
-
-    /// Move assignment
     buffer_cat_view& operator=(buffer_cat_view&&) = default;
 
-    // Copy assignment
+    /// Assignment
     buffer_cat_view& operator=(buffer_cat_view const&) = default;
 
     /** Constructor
@@ -67,11 +58,16 @@ public:
     explicit
     buffer_cat_view(Buffers const&... buffers);
 
-    /// Return an iterator to the beginning of the concatenated sequence.
+    //-----
+
+    /// Required for @b BufferSequence
+    buffer_cat_view(buffer_cat_view const&) = default;
+
+    /// Required for @b BufferSequence
     const_iterator
     begin() const;
 
-    /// Return an iterator to the end of the concatenated sequence.
+    /// Required for @b BufferSequence
     const_iterator
     end() const;
 };

include/beast/core/buffer_prefix.hpp

@@ -83,7 +83,7 @@ public:
 
     /** Construct a buffer sequence prefix.
 
-        @param n The maximum number of bytes in the prefix.
+        @param size The maximum number of bytes in the prefix.
         If this is larger than the size of passed, buffers,
         the resulting sequence will represent the entire
         input sequence.

include/beast/core/consuming_buffers.hpp

@@ -36,17 +36,20 @@ namespace beast {
 template<class BufferSequence>
 class consuming_buffers
 {
+    using buffers_type =
+        typename std::decay<BufferSequence>::type;
+
     using iter_type =
-        typename BufferSequence::const_iterator;
+        typename buffers_type::const_iterator;
 
     BufferSequence bs_;
     iter_type begin_;
     std::size_t skip_ = 0;
 
     template<class Deduced>
-    consuming_buffers(Deduced&& other, std::size_t nbegin)
+    consuming_buffers(Deduced&& other, std::size_t dist)
         : bs_(std::forward<Deduced>(other).bs_)
-        , begin_(std::next(bs_.begin(), nbegin))
+        , begin_(std::next(bs_.begin(), dist))
         , skip_(other.skip_)
     {
     }
@@ -60,7 +63,7 @@ public:
         `boost::asio::const_buffer`.
     */
 #if BEAST_DOXYGEN
-    using value_type = ...;
+    using value_type = implementation_defined;
 #else
     using value_type = typename std::conditional<
         std::is_convertible<typename
@@ -82,13 +85,13 @@ public:
     /// Constructor
     consuming_buffers();
 
-    /// Move constructor
+    /// Constructor
     consuming_buffers(consuming_buffers&&);
 
-    /// Copy constructor
+    /// Constructor
     consuming_buffers(consuming_buffers const&);
 
-    /** Construct to represent a buffer sequence.
+    /** Constructor
 
         A copy of the buffer sequence is made. Ownership of the
         underlying memory is not transferred or copied.
@@ -96,17 +99,20 @@ public:
     explicit
     consuming_buffers(BufferSequence const& buffers);
 
-    /** Construct a buffer sequence in-place.
+    /** Constructor
 
-        @param args Arguments forwarded to the contained buffers constructor.
+        This constructs the buffer sequence in-place from
+        a list of arguments.
+
+        @param args Arguments forwarded to the buffers constructor.
     */
     template<class... Args>
     consuming_buffers(boost::in_place_init_t, Args&&... args);
 
-    /// Move assignment
+    /// Assignment
     consuming_buffers& operator=(consuming_buffers&&);
 
-    /// Copy assignmen
+    /// Assignmen
     consuming_buffers& operator=(consuming_buffers const&);
 
     /// Get a bidirectional iterator to the first element.
@@ -119,12 +125,12 @@ public:
 
     /** Remove bytes from the beginning of the sequence.
 
-        @param n The number of bytes to remove. If this is
+        @param amount The number of bytes to remove. If this is
         larger than the number of bytes remaining, all the
         bytes remaining are removed.
     */
     void
-    consume(std::size_t n);
+    consume(std::size_t amount);
 };
 
 } // beast

include/beast/core/drain_buffer.hpp

@@ -113,7 +113,7 @@ public:
         This call has no effect.
     */
     void
-    consume(std::size_t) const
+    consume(std::size_t)
     {
     }
 };

include/beast/core/flat_buffer.hpp

@@ -127,7 +127,7 @@ public:
     basic_flat_buffer(
         std::size_t limit, Allocator const& alloc);
 
-    /** Move constructor
+    /** Constructor
 
         After the move, `*this` will have an empty output sequence.
 
@@ -137,7 +137,7 @@ public:
     */
     basic_flat_buffer(basic_flat_buffer&& other);
 
-    /** Move constructor
+    /** Constructor
 
         After the move, `*this` will have an empty output sequence.
 
@@ -150,13 +150,13 @@ public:
     basic_flat_buffer(
         basic_flat_buffer&& other, Allocator const& alloc);
 
-    /** Copy constructor
+    /** Constructor
 
         @param other The object to copy from.
     */
     basic_flat_buffer(basic_flat_buffer const& other);
 
-    /** Copy constructor
+    /** Constructor
 
         @param other The object to copy from.
 
@@ -165,7 +165,7 @@ public:
     basic_flat_buffer(basic_flat_buffer const& other,
         Allocator const& alloc);
 
-    /** Copy constructor
+    /** Constructor
 
         @param other The object to copy from.
     */
@@ -173,7 +173,7 @@ public:
     basic_flat_buffer(
         basic_flat_buffer<OtherAlloc> const& other);
 
-    /** Copy constructor
+    /** Constructor
 
         @param other The object to copy from.
 
@@ -184,18 +184,18 @@ public:
         basic_flat_buffer<OtherAlloc> const& other,
             Allocator const& alloc);
 
-    /** Move assignment
+    /** Assignment
 
         After the move, `*this` will have an empty output sequence.
 
         @param other The object to move from. After the move,
-        The object's state will be as if constructed using
+        the object's state will be as if constructed using
         its current allocator and limit.
     */
     basic_flat_buffer&
     operator=(basic_flat_buffer&& other);
 
-    /** Copy assignment
+    /** Assignment
 
         After the copy, `*this` will have an empty output sequence.
 

include/beast/core/impl/consuming_buffers.ipp

@@ -168,10 +168,10 @@ consuming_buffers<Buffers>::
 operator=(consuming_buffers&& other) ->
     consuming_buffers&
 {
-    auto const nbegin = std::distance<iter_type>(
+    auto const dist = std::distance<iter_type>(
         other.bs_.begin(), other.begin_);
     bs_ = std::move(other.bs_);
-    begin_ = std::next(bs_.begin(), nbegin);
+    begin_ = std::next(bs_.begin(), dist);
     skip_ = other.skip_;
     return *this;
 }
@@ -182,10 +182,10 @@ consuming_buffers<Buffers>::
 operator=(consuming_buffers const& other) ->
     consuming_buffers&
 {
-    auto const nbegin = std::distance<iter_type>(
+    auto const dist = std::distance<iter_type>(
         other.bs_.begin(), other.begin_);
     bs_ = other.bs_;
-    begin_ = std::next(bs_.begin(), nbegin);
+    begin_ = std::next(bs_.begin(), dist);
     skip_ = other.skip_;
     return *this;
 }
@@ -213,19 +213,19 @@ end() const ->
 template<class Buffers>
 void
 consuming_buffers<Buffers>::
-consume(std::size_t n)
+consume(std::size_t amount)
 {
     using boost::asio::buffer_size;
-    for(;n > 0 && begin_ != bs_.end(); ++begin_)
+    for(;amount > 0 && begin_ != bs_.end(); ++begin_)
     {
         auto const len =
             buffer_size(*begin_) - skip_;
-        if(n < len)
+        if(amount < len)
         {
-            skip_ += n;
+            skip_ += amount;
             break;
         }
-        n -= len;
+        amount -= len;
         skip_ = 0;
     }
 }

include/beast/http/file_body.hpp

@@ -514,6 +514,14 @@ finish(error_code& ec)
 /// A message body represented by a file on the filesystem.
 using file_body = basic_file_body<file>;
 
+#if ! BEAST_DOXYGEN
+// operator<< is not supported for file_body
+template<bool isRequest, class File, class Fields>
+std::ostream&
+operator<<(std::ostream& os, message<
+    isRequest, basic_file_body<File>, Fields> const& msg) = delete;
+#endif
+
 } // http
 } // beast
 

include/beast/websocket/stream.hpp

@@ -281,7 +281,7 @@ public:
     using lowest_layer_type =
         typename get_lowest_layer<next_layer_type>::type;
 
-    /** Move constructor
+    /** Constructor
 
         If @c NextLayer is move constructible, this function
         will move-construct a new stream from the existing stream.
@@ -291,7 +291,7 @@ public:
     */
     stream(stream&&) = default;
 
-    /** Move assignment
+    /** Assignment
 
         If `NextLayer` is move assignable, this function
         will move-assign a new stream from the existing stream.
@@ -416,7 +416,7 @@ public:
 
         The default setting is to fragment messages.
 
-        @param v A `bool` indicating if auto fragmentation should be on.
+        @param value A `bool` indicating if auto fragmentation should be on.
 
         @par Example
         Setting the automatic fragmentation option:
@@ -425,9 +425,9 @@ public:
         @endcode
     */
     void
-    auto_fragment(bool v)
+    auto_fragment(bool value)
     {
-        wr_autofrag_ = v;
+        wr_autofrag_ = value;
     }
 
     /// Returns `true` if the automatic fragmentation option is set.
@@ -447,7 +447,7 @@ public:
 
         The default setting is to send text messages.
 
-        @param v `true` if outgoing messages should indicate
+        @param value `true` if outgoing messages should indicate
         binary, or `false` if they should indicate text.
 
         @par Example
@@ -457,9 +457,9 @@ public:
         @endcode
         */
     void
-    binary(bool v)
+    binary(bool value)
     {
-        wr_opcode_ = v ?
+        wr_opcode_ = value ?
             detail::opcode::binary :
             detail::opcode::text;
     }
@@ -529,7 +529,7 @@ public:
 
         The default setting is 4096. The minimum value is 8.
 
-        @param n The size of the read buffer.
+        @param amount The size of the read buffer.
 
         @throws std::invalid_argument If the buffer size is less than 8.
 
@@ -540,12 +540,12 @@ public:
         @endcode
     */
     void
-    read_buffer_size(std::size_t n)
+    read_buffer_size(std::size_t amount)
     {
-        if(n < 8)
+        if(amount < 8)
             BOOST_THROW_EXCEPTION(std::invalid_argument{
                 "read buffer size underflow"});
-        rd_buf_size_ = n;
+        rd_buf_size_ = amount;
     }
 
     /// Returns the read buffer size setting.
@@ -570,12 +570,12 @@ public:
             ws.read_message_max(65536);
         @endcode
 
-        @param n The limit on the size of incoming messages.
+        @param amount The limit on the size of incoming messages.
     */
     void
-    read_message_max(std::size_t n)
+    read_message_max(std::size_t amount)
     {
-        rd_msg_max_ = n;
+        rd_msg_max_ = amount;
     }
 
     /// Returns the maximum incoming message size setting.
@@ -608,15 +608,15 @@ public:
             ws.write_buffer_size(8192);
         @endcode
 
-        @param n The size of the write buffer in bytes.
+        @param amount The size of the write buffer in bytes.
     */
     void
-    write_buffer_size(std::size_t n)
+    write_buffer_size(std::size_t amount)
     {
-        if(n < 8)
+        if(amount < 8)
             BOOST_THROW_EXCEPTION(std::invalid_argument{
                 "write buffer size underflow"});
-        wr_buf_size_ = n;
+        wr_buf_size_ = amount;
     };
 
     /// Returns the size of the write buffer.
@@ -636,7 +636,7 @@ public:
 
         The default setting is to send text messages.
 
-        @param v `true` if outgoing messages should indicate
+        @param value `true` if outgoing messages should indicate
         text, or `false` if they should indicate binary.
 
         @par Example
@@ -646,9 +646,9 @@ public:
         @endcode
     */
     void
-    text(bool v)
+    text(bool value)
     {
-        wr_opcode_ = v ?
+        wr_opcode_ = value ?
             detail::opcode::text :
             detail::opcode::binary;
     }
@@ -826,7 +826,8 @@ public:
     */
     template<class ResponseDecorator>
     void
-    accept_ex(ResponseDecorator const& decorator,
+    accept_ex(
+        ResponseDecorator const& decorator,
         error_code& ec);
 
     /** Read and respond to a WebSocket HTTP Upgrade request.
@@ -911,7 +912,8 @@ public:
     typename std::enable_if<! http::detail::is_header<
         ConstBufferSequence>::value>::type
 #endif
-    accept_ex(ConstBufferSequence const& buffers,
+    accept_ex(
+        ConstBufferSequence const& buffers,
         ResponseDecorator const& decorator);
 
     /** Read and respond to a WebSocket HTTP Upgrade request.
@@ -949,7 +951,9 @@ public:
     typename std::enable_if<! http::detail::is_header<
         ConstBufferSequence>::value>::type
 #endif
-    accept(ConstBufferSequence const& buffers, error_code& ec);
+    accept(
+        ConstBufferSequence const& buffers,
+        error_code& ec);
 
     /** Read and respond to a WebSocket HTTP Upgrade request.
 
@@ -988,15 +992,15 @@ public:
 
         @param ec Set to indicate what error occurred, if any.
     */
-    template<class ConstBufferSequence,
+    template<class ConstBufferSequence, class ResponseDecorator>
-        class ResponseDecorator>
 #if BEAST_DOXYGEN
     void
 #else
     typename std::enable_if<! http::detail::is_header<
         ConstBufferSequence>::value>::type
 #endif
-    accept_ex(ConstBufferSequence const& buffers,
+    accept_ex(
+        ConstBufferSequence const& buffers,
         ResponseDecorator const& decorator,
         error_code& ec);
 
@@ -1867,7 +1871,9 @@ public:
         @endcode
     */
     void
-    handshake(string_view host, string_view target);
+    handshake(
+        string_view host,
+        string_view target);
 
     /** Send an HTTP WebSocket Upgrade request and receive the response.
 
@@ -1913,8 +1919,10 @@ public:
         @endcode
     */
     void
-    handshake(response_type& res,
+    handshake(
-        string_view host, string_view target);
+        response_type& res,
+        string_view host,
+        string_view target);
 
     /** Send an HTTP WebSocket Upgrade request and receive the response.
 
@@ -1970,7 +1978,9 @@ public:
     */
     template<class RequestDecorator>
     void
-    handshake_ex(string_view host, string_view target,
+    handshake_ex(
+        string_view host,
+        string_view target,
         RequestDecorator const& decorator);
 
     /** Send an HTTP WebSocket Upgrade request and receive the response.
@@ -2031,8 +2041,10 @@ public:
     */
     template<class RequestDecorator>
     void
-    handshake_ex(response_type& res,
+    handshake_ex(
-        string_view host, string_view target,
+        response_type& res,
+        string_view host,
+        string_view target,
         RequestDecorator const& decorator);
 
     /** Send an HTTP WebSocket Upgrade request and receive the response.
@@ -2073,8 +2085,10 @@ public:
         @endcode
     */
     void
-    handshake(string_view host,
+    handshake(
-        string_view target, error_code& ec);
+        string_view host,
+        string_view target,
+        error_code& ec);
 
     /** Send an HTTP WebSocket Upgrade request and receive the response.
 
@@ -2093,6 +2107,9 @@ public:
         a successful HTTP Upgrade (represented by a Status-Code of 101,
         "switching protocols").
 
+        @param res The HTTP Upgrade response returned by the remote
+        endpoint. If `ec` is set, the returned value is undefined.
+
         @param host The name of the remote host,
         required by the HTTP protocol.
 
@@ -2101,9 +2118,6 @@ public:
 
         @param ec Set to indicate what error occurred, if any.
 
-        @param res The HTTP Upgrade response returned by the remote
-        endpoint. If `ec is set, the return value is undefined.
-
         @par Example
         @code
         websocket::stream<ip::tcp::socket> ws{io_service};
@@ -2118,8 +2132,11 @@ public:
         @endcode
     */
     void
-    handshake(response_type& res,
+    handshake(
-        string_view host, string_view target, error_code& ec);
+        response_type& res,
+        string_view host,
+        string_view target,
+        error_code& ec);
 
     /** Send an HTTP WebSocket Upgrade request and receive the response.
 
@@ -2174,8 +2191,10 @@ public:
     */
     template<class RequestDecorator>
     void
-    handshake_ex(string_view host,
+    handshake_ex(
-        string_view target, RequestDecorator const& decorator,
+        string_view host,
+        string_view target,
+        RequestDecorator const& decorator,
         error_code& ec);
 
     /** Send an HTTP WebSocket Upgrade request and receive the response.
@@ -2235,9 +2254,12 @@ public:
     */
     template<class RequestDecorator>
     void
-    handshake_ex(response_type& res,
+    handshake_ex(
-        string_view host, string_view target,
+        response_type& res,
-            RequestDecorator const& decorator, error_code& ec);
+        string_view host,
+        string_view target,
+        RequestDecorator const& decorator,
+        error_code& ec);
 
     /** Start an asynchronous operation to send an upgrade request and receive the response.
 
@@ -2286,8 +2308,10 @@ public:
     async_return_type<
         HandshakeHandler, void(error_code)>
 #endif
-    async_handshake(string_view host,
+    async_handshake(
-        string_view target, HandshakeHandler&& handler);
+        string_view host,
+        string_view target,
+        HandshakeHandler&& handler);
 
     /** Start an asynchronous operation to send an upgrade request and receive the response.
 
@@ -2340,8 +2364,10 @@ public:
     async_return_type<
         HandshakeHandler, void(error_code)>
 #endif
-    async_handshake(response_type& res,
+    async_handshake(
-        string_view host, string_view target,
+        response_type& res,
+        string_view host,
+        string_view target,
         HandshakeHandler&& handler);
 
     /** Start an asynchronous operation to send an upgrade request and receive the response.
@@ -2400,8 +2426,10 @@ public:
     async_return_type<
         HandshakeHandler, void(error_code)>
 #endif
-    async_handshake_ex(string_view host,
+    async_handshake_ex(
-        string_view target, RequestDecorator const& decorator,
+        string_view host,
+        string_view target,
+        RequestDecorator const& decorator,
         HandshakeHandler&& handler);
 
     /** Start an asynchronous operation to send an upgrade request and receive the response.
@@ -2464,8 +2492,10 @@ public:
     async_return_type<
         HandshakeHandler, void(error_code)>
 #endif
-    async_handshake_ex(response_type& res,
+    async_handshake_ex(
-        string_view host, string_view target,
+        response_type& res,
+        string_view host,
+        string_view target,
         RequestDecorator const& decorator,
         HandshakeHandler&& handler);