add more documentation to client modules

CHANGELOG.md

@@ -10,6 +10,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ### Fixed
 - Randomized ports for client connections and message ids, #23
 - OpCode::From for u8 removed, added OpCode::from_u8(), #36
+- Fix for named startup related to ipv6, #56
 
 ### Changed
 - Upgraded OpenSSL to 0.8.* #50

src/client/client.rs

@@ -31,11 +31,13 @@ use ::serialize::binary::*;
 use ::client::ClientConnection;
 
 /// The Client is abstracted over either trust_dns::tcp::TcpClientConnection or
-///  trust_dns::udp::UdpClientConnection, usage of TCP or UDP is up to the user. Some DNS servers
+///  trust_dns::udp::UdpClientConnection
+///
+/// Usage of TCP or UDP is up to the user. Some DNS servers
 ///  disallow TCP in some cases, so if TCP double check if UDP works.
 ///
-/// *note* As of 0.8.0, Client as been deprecated in favor of ClientFuture
-#[deprecated]
+/// *note* As of 0.8.0, Client as been deprecated in favor of `trust_dns::client::ClientFuture`
+#[deprecated = "see trust_dns::client::ClientFuture"]
 pub struct Client<C: ClientConnection> {
   client_connection: RefCell<C>,
   trust_anchor: TrustAnchor,

src/client/client_future.rs

@@ -30,6 +30,10 @@ const QOS_MAX_RECEIVE_MSGS: usize = 100; // max number of messages to receive fr
 
 type StreamHandle = Sender<Vec<u8>>;
 
+/// A DNS Client implemented over futures-rs.
+///
+/// This Client is generic and capable of wrapping UDP, TCP, and other underlying DNS protocol
+///  implementations.
 #[must_use = "futures do nothing unless polled"]
 pub struct ClientFuture<S: Stream<Item=Vec<u8>, Error=io::Error>> {
   stream: S,
@@ -284,8 +288,12 @@ impl<S: Stream<Item=Vec<u8>, Error=io::Error> + 'static> Future for ClientFuture
   }
 }
 
+/// Root ClientHandle implementaton returned by ClientFuture
+///
+/// This can be used directly to perform queries. See `trust_dns::client::SecureClientHandle` for
+///  a DNSSEc chain validator.
 #[derive(Clone)]
-#[must_use = "futures do nothing unless polled"]
+#[must_use = "queries can only be sent through a ClientHandle"]
 pub struct BasicClientHandle {
   message_sender: Sender<(Message, Complete<ClientResult<Message>>)>,
 }
@@ -309,6 +317,8 @@ impl ClientHandle for BasicClientHandle {
   }
 }
 
+/// A trait for implementing high level functions of DNS.
+#[must_use = "queries can only be sent through a ClientHandle"]
 pub trait ClientHandle: Clone {
   /// Send a message via the channel in the client
   ///
@@ -319,7 +329,7 @@ pub trait ClientHandle: Clone {
   ///               being stable.
   fn send(&self, message: Message) -> Box<Future<Item=Message, Error=ClientError>>;
 
-  /// A *classic* DNS query, i.e. does not perform and DNSSec operations
+  /// A *classic* DNS query
   ///
   /// *Note* As of now, this will not recurse on PTR or CNAME record responses, that is up to
   ///        the caller.
@@ -329,9 +339,6 @@ pub trait ClientHandle: Clone {
   /// * `name` - the label to lookup
   /// * `query_class` - most likely this should always be DNSClass::IN
   /// * `query_type` - record type to lookup
-  ///
-  /// TODO: The result of this should be generified to allow for Caches and SecureBasicClientHandle
-  ///  to all share a trait
   fn query(&self, name: domain::Name, query_class: DNSClass, query_type: RecordType)
     -> Box<Future<Item=Message, Error=ClientError>> {
     debug!("querying: {} {:?}", name, query_type);

src/client/memoize_client_handle.rs

@@ -15,13 +15,20 @@ use ::client::rc_future::{rc_future, RcFuture};
 use ::error::*;
 use ::op::{Message, Query};
 
+/// Will return memoized (cached) responses to queries
+///
+/// This wraps a ClientHandle, changing the implementation `send()` to store the response against
+///  the Message.Query that was sent. This should reduce network traffic especially during things
+///  like DNSSec validation. *Warning* this will currently cache for the life of the Client.
 #[derive(Clone)]
+#[must_use = "queries can only be sent through a ClientHandle"]
 pub struct MemoizeClientHandle<H: ClientHandle> {
   client: H,
   active_queries: Rc<RefCell<HashMap<Query, RcFuture<Box<Future<Item=Message, Error=ClientError>>>>>>,
 }
 
 impl<H> MemoizeClientHandle<H> where H: ClientHandle {
+  /// Returns a new handle wrapping the specified client
   pub fn new(client: H) -> MemoizeClientHandle<H> {
     MemoizeClientHandle { client: client, active_queries: Rc::new(RefCell::new(HashMap::new())) }
   }

src/client/retry_client_handle.rs

@@ -11,7 +11,11 @@ use ::client::ClientHandle;
 use ::error::*;
 use ::op::Message;
 
+/// Can be used to reattempt a queries if they fail
+///
+/// *note* Current value of this is not clear, it may be removed
 #[derive(Clone)]
+#[must_use = "queries can only be sent through a ClientHandle"]
 pub struct RetryClientHandle<H: ClientHandle> {
   client: H,
   attempts: usize,

src/client/secure_client_handle.rs

@@ -28,12 +28,13 @@ struct Rrset {
     pub records: Vec<Record>,
 }
 
-/// A ClientHandle which will return DNSSec validating futures.
+/// Performs DNSSec validation of all DNS responses from the wrapped ClientHandle
 ///
 /// This wraps a ClientHandle, changing the implementation `send()` to validate all
 ///  message responses for Query operations. Update operation responses are not validated by
 ///  this process.
 #[derive(Clone)]
+#[must_use = "queries can only be sent through a ClientHandle"]
 pub struct SecureClientHandle<H: ClientHandle + 'static> {
   client: H,
   trust_anchor: Rc<TrustAnchor>,