From: Marcin Siodelski <marcin@isc.org>
Date: Mon, 2 Jan 2017 16:25:52 +0000 (+0100)
Subject: [5094] Added documentation to the TCPAcceptor class.
X-Git-Tag: trac5090_base~1^2~5
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=115a3f2036b3001f4a596c6f9be14a6c42b2e708;p=thirdparty%2Fkea.git

[5094] Added documentation to the TCPAcceptor class.
---

diff --git a/src/lib/asiolink/io_asio_socket.h b/src/lib/asiolink/io_asio_socket.h
index faeb6171e3..f043674d37 100644
--- a/src/lib/asiolink/io_asio_socket.h
+++ b/src/lib/asiolink/io_asio_socket.h
@@ -78,6 +78,8 @@ class IOEndpoint;
 
 template <typename C>
 class IOAsioSocket : public IOSocket {
+public:
+
     ///
     /// \name Constructors and Destructor
     ///
diff --git a/src/lib/asiolink/tcp_acceptor.h b/src/lib/asiolink/tcp_acceptor.h
index 85879fa010..a5f1630e3d 100644
--- a/src/lib/asiolink/tcp_acceptor.h
+++ b/src/lib/asiolink/tcp_acceptor.h
@@ -21,53 +21,103 @@
 namespace isc {
 namespace asiolink {
 
+/// @brief Provides a service for accepting new TCP connections.
+///
+/// Internally it uses @c boost::asio::ip::tcp::acceptor class to implement
+/// the acceptor service.
+///
+/// @tparam Acceptor callback type.
 template<typename C>
-class TCPAcceptor : public IOSocket{
+class TCPAcceptor : public IOSocket {
 public:
 
-    TCPAcceptor(IOService& io_service)
+    /// @brief Constructor.
+    ///
+    /// @param io_service IO service.
+    explicit TCPAcceptor(IOService& io_service)
         : IOSocket(),
           acceptor_(new boost::asio::ip::tcp::acceptor(io_service.get_io_service())) {
     }
 
+    /// @brief Destructor.
     virtual ~TCPAcceptor() { }
 
-    virtual int getNative() const {
+    /// @brief Returns file descriptor of the underlying socket.
+    virtual int getNative() const final {
         return (acceptor_->native());
     }
 
-    virtual int getProtocol() const {
+    /// @brief Returns protocol of the socket.
+    ///
+    /// @return IPPROTO_TCP.
+    virtual int getProtocol() const final {
         return (IPPROTO_TCP);
     }
 
+    /// @brief Opens acceptor socket given the endpoint.
+    ///
+    /// @param endpoint Reference to the endpoint object which specifies the
+    /// address and port on which the acceptor service will run.
     void open(const TCPEndpoint& endpoint) {
         acceptor_->open(endpoint.getASIOEndpoint().protocol());
     }
 
+    /// @brief Sets socket option.
+    ///
+    /// Typically, this method is used to set SO_REUSEADDR option on the socket:
+    /// @code
+    /// IOService io_service;
+    /// TCPAcceptor<Callback> acceptor(io_service);
+    /// acceptor.setOption(TCPAcceptor::ReuseAddress(true))
+    /// @endcode
+    ///
+    /// @param socket_option Reference to the object encapsulating an option to
+    /// be set for the socket.
+    /// @tparam SettableSocketOption Type of the object encapsulating socket option
+    /// being set.
     template<typename SettableSocketOption>
     void setOption(const SettableSocketOption& socket_option) {
         acceptor_->set_option(socket_option);
     }
 
+    /// @brief Binds socket to an endpoint.
+    ///
+    /// @param endpoint Reference to an endpoint to which the socket is to
+    /// be bound.
     void bind(const TCPEndpoint& endpoint) {
         acceptor_->bind(endpoint.getASIOEndpoint());
     }
 
+    /// @brief Starts listening for the new connections.
     void listen() {
         acceptor_->listen();
     }
 
+    /// @brief Asynchronously accept new connection.
+    ///
+    /// This method accepts new connection into the specified socket. When the
+    /// new connection arrives or an error occurs the specified callback function
+    /// is invoked.
+    ///
+    /// @param socket Socket into which connection should be accepted.
+    /// @param callback Callback function to be invoked when the new connection
+    /// arrives.
+    /// @tparam SocketCallback Type of the callback for the @ref TCPSocket.
     template<typename SocketCallback>
     void asyncAccept(const TCPSocket<SocketCallback>& socket, C& callback) {
         acceptor_->async_accept(socket.getASIOSocket(), callback);
     }
 
+    /// @brief Checks if the acceptor is open.
+    ///
+    /// @return true if acceptor is open.
     bool isOpen() const {
         return (acceptor_->is_open());
     }
 
 private:
 
+    /// @brief Underlying ASIO acceptor implementation.
     boost::shared_ptr<boost::asio::ip::tcp::acceptor> acceptor_;
 
 };