[trac999] overall documentation updates

src/lib/acl/ip_check.h

@@ -114,12 +114,57 @@ T createNetmask(size_t masksize) {
 std::pair<std::string, int>
 splitIPAddress(const std::string& addrmask);
 
-/// \brief A simple representation of IP address
+/// \brief A simple representation of IP address.
 ///
+/// This structure provides address family independent interfaces of an
+/// IP(v4 or v6) address, so that the application can perform
+/// \c IPCheck::matches without knowing which version of address it is
+/// handling.  (For example, consider the standard socket API: it uses
+/// the generic \c sockaddr structure to represent endpoints).
+///
+/// An object of this class could be constructed from various types of
+/// sources, but in the initial implementation there's only one constructor,
+/// which takes a \c sockaddr structure.  For efficiency the \c IPAddress
+/// object only retains a reference to the necessary part of \c sockaddr.
+/// Therefore the corresponding \c sockaddr instance must be valid while the
+/// \c IPAddress object is used.
+///
+/// This class is copyable so that a fixed object can be easily reused for
+/// different addresses.  To ensure internal integrity, specific member
+/// variables are kept private and only accessible via read-only accessor
+/// methods.  Due to this, it is ensured, for example, that if \c getFamily()
+/// returns \c AF_INET6, \c getLength() always returns 16.
+///
+/// All accessor methods are straightforward and exception free.
+///
+/// In future, we may introduce the default constructor to further improve
+/// reusability.
 struct IPAddress {
+    /// The constructor from socket address structure.
+    ///
+    /// This constructor set up the internal data based on the actual type
+    /// \c sa.  For example, if \c sa.sa_family is \c AF_INET, it assumes
+    /// \c sa actually refers to a \c sockaddr_in structure.
+    /// The behavior when this assumption isn't held is undefined.
+    ///
+    /// \param sa A reference to the socket address structure from which the
+    /// \c IPAddress is to be constructed.
     explicit IPAddress(const struct sockaddr& sa);
+
+    /// Return the address family of the address
+    ///
+    /// It's AF_INET for IPv4 and AF_INET6 for IPv6.
     int getFamily() const { return (family); }
+
+    /// Return the binary representation of the address in network byte order.
+    ///
+    /// Only the \c getLength() bytes from the returned pointer are ensured
+    /// to be valid.  In addition, if the \c sockaddr structure given on
+    /// construction was dynamically allocated, the data is valid only until
+    /// the \c sockaddr is invalidated.
     const uint8_t* getData() const { return (data); }
+
+    /// Return the length of the address.
     size_t getLength() const { return (length); }
 private:
     int family;

src/lib/server_common/client.h

@@ -22,27 +22,110 @@
 
 #include <acl/ip_check.h>
 
-#include <asiolink/io_message.h>
-
 namespace isc {
+namespace asiolink {
+class IOMessage;
+class IOEndpoint;
+}
+
 namespace acl {
 struct IPAddress;
 }
 
 namespace server_common {
 
-/// May have to be named something like "DNSClient"
-/// should be reusable
-/// may want to use different subclasses for auth clients and resolver clients
+/// A DNS client with a single request context.
+///
+/// The \c Client class represents a DNS client with information of one
+/// DNS request (e.g., a query).  The information includes the source and
+/// destination IP addresses of the request, information of the DNS request
+/// message such as the query name or (if provided) TSIG key information.
+///
+/// A \c Client class object is expected to be constructed on receiving a
+/// new request with lower level information such as IP addresses and is
+/// updated with DNS specific information as the server processes the request.
+/// It is also expected to be used as the primary interface for request
+/// processing such as query handling or access control.
+///
+/// Furthermore, to minimize the overhead, this class would be further
+/// extended so that it can be reusable with an additional method to reset
+/// the internal information.
+///
+/// In the current initial implementation, however, it only contains the
+/// lower level information in the form of \c IOMessage object and cannot
+/// be reused (it must be constructed for every new request).  Also, the
+/// only actual usage of this class at this moment is for ACL handling.
+///
+/// A \c Client class object is generally assumed to be valid throughout
+/// the processing of a single request, and then be destructed or (when
+/// supported) reset.  To avoid it is copied and held accidentally beyond
+/// the expected valid period, it is intentionally made non copyable.
+///
+/// Notes about other possibilities: we may want to abstract it further,
+/// so that it can also be used for DHCP.  In that case, we'd subclass a
+/// base client class for DNS specific clients and DHCP specific clients.
+/// We might also want to separate DNS clients for authoritative servers
+/// and clients for the resolver, especially because the former could be
+/// simpler with performance optimizations.
 class Client : boost::noncopyable {
 public:
+    ///
+    /// \name Constructors and Destructor
+    ///
+    //@{
+    /// The constructor.
+    ///
+    /// This initial version of constructor takes an \c IOMessage object
+    /// that is supposed to represent a DNS request message sent from an
+    /// external client (but the constructor does not perform any assumption
+    /// check on the given \c IOMessage).
+    ///
+    /// If and when we extend the behavior and responsibility
+    /// of this class, this version of constructor will probably be
+    /// deprecated.
+    ///
+    /// \c request_message must be valid throughout the lifetime of the client.
+    ///
+    /// \exception None
+    /// \param request_message Refers to \c IOMessage corresponding to some
+    /// DNS request message.
     explicit Client(const isc::asiolink::IOMessage& request_message);
+
+    /// The destructor
     ~Client();
+    //@}
+
+    /// Return the client's endpoint of the request.
+    ///
+    /// This should be identical to the result of \c getRemoteEndpoint()
+    /// called on \c request_message passed to the constructor.
+    ///
+    /// \exception None
     const isc::asiolink::IOEndpoint& getRequestSourceEndpoint() const;
 
-    // convenience shortcut
+    /// Return the IP address part of the client request's endpoint.
+    ///
+    /// The resulting \c IPAddress can be constructed using
+    /// \c getRequestSourceEndpoint(), and in that sense this method is
+    /// redundant.  But this implementation internally constructs the
+    /// \c IPAddress on construction and always returns a reference to it,
+    /// and should be more efficient.  It is provided so that it can be
+    /// called multiple times in a complicated ACL with minimum cost.
+    ///
+    /// \exception None
     const isc::acl::IPAddress& getRequestSourceIPAddress() const;
 
+    /// Convert the Client to a string.
+    ///
+    /// (In the initial implementation) the format of the resulting string
+    /// is as follows:
+    /// \code <IP address>#<port>
+    /// \endcode
+    /// The IP address is the textual representation of the client's IP
+    /// address, which is the source address of the request the client has
+    /// sent.  The port is the UDP or TCP of the client's end of the request.
+    ///
+    /// \exception std::bad_alloc Internal resource allocation fails
     std::string toText() const;
 
 private:
@@ -64,6 +147,11 @@ std::ostream& operator<<(std::ostream& os, const Client& client);
 }
 
 namespace acl {
+/// The specialization of \c IPCheck for access control with \c Client.
+///
+/// It returns \c true if the source IP address of the client's request
+/// matches the expression encapsulated in the \c IPCheck, and returns
+/// \c false if not.
 template <>
 bool IPCheck<server_common::Client>::matches(
     const server_common::Client& client) const;