add documentation

2 files changed, 517 insertions, 1 deletions

diff --git a/ipfs-api/src/client.rs b/ipfs-api/src/client.rs
index 1a7dc89..a31bead 100644
--- a/ipfs-api/src/client.rs
+++ b/ipfs-api/src/client.rs
@@ -22,7 +22,7 @@ use tokio_core::reactor::Handle;
 use tokio_io::codec::{Decoder, FramedRead};
 
 
-/// A future response returned by the reqwest HTTP client.
+/// A response returned by the HTTP client.
 ///
 type AsyncResponse<T> = Box<Future<Item = T, Error = Error>>;
 
@@ -347,6 +347,25 @@ impl IpfsClient {
 impl IpfsClient {
     /// Add file to Ipfs.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use std::io::Cursor;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    /// let data = Cursor::new("Hello World!");
+    ///
+    /// core.run(client.add(data));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn add<R>(&self, data: R) -> AsyncResponse<response::AddResponse>
     where
@@ -361,6 +380,23 @@ impl IpfsClient {
 
     /// Returns the current ledger for a peer.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.bitswap_ledger("QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ"));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn bitswap_ledger(&self, peer: &str) -> AsyncResponse<response::BitswapLedgerResponse> {
         self.request(&request::BitswapLedger { peer }, None)
@@ -368,6 +404,23 @@ impl IpfsClient {
 
     /// Returns some stats about the bitswap agent.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.bitswap_stat());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn bitswap_stat(&self) -> AsyncResponse<response::BitswapStatResponse> {
         self.request(&request::BitswapStat, None)
@@ -375,6 +428,23 @@ impl IpfsClient {
 
     /// Remove a given block from your wantlist.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.bitswap_unwant("QmXdNSQx7nbdRvkjGCEQgVjVtVwsHvV8NmV2a8xzQVwuFA"));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn bitswap_unwant(&self, key: &str) -> AsyncResponse<response::BitswapUnwantResponse> {
         self.request_empty(&request::BitswapUnwant { key }, None)
@@ -382,6 +452,23 @@ impl IpfsClient {
 
     /// Shows blocks on the wantlist for you or the specified peer.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.bitswap_wantlist(Some("QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ")));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn bitswap_wantlist(
         &self,
@@ -392,6 +479,26 @@ impl IpfsClient {
 
     /// Gets a raw IPFS block.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate futures;
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use futures::stream::Stream;
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    /// let hash = "QmXdNSQx7nbdRvkjGCEQgVjVtVwsHvV8NmV2a8xzQVwuFA";
+    ///
+    /// core.run(client.block_get(hash).concat2());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn block_get(&self, hash: &str) -> AsyncStreamResponse<Chunk> {
         self.request_stream_bytes(&request::BlockGet { hash }, None)
@@ -399,6 +506,25 @@ impl IpfsClient {
 
     /// Store input as an IPFS block.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use std::io::Cursor;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    /// let data = Cursor::new("Hello World!");
+    ///
+    /// core.run(client.block_put(data));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn block_put<R>(&self, data: R) -> AsyncResponse<response::BlockPutResponse>
     where
@@ -413,6 +539,23 @@ impl IpfsClient {
 
     /// Removes an IPFS block.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.block_rm("QmXdNSQx7nbdRvkjGCEQgVjVtVwsHvV8NmV2a8xzQVwuFA"));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn block_rm(&self, hash: &str) -> AsyncResponse<response::BlockRmResponse> {
         self.request(&request::BlockRm { hash }, None)
@@ -420,6 +563,23 @@ impl IpfsClient {
 
     /// Prints information about a raw IPFS block.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.block_stat("QmXdNSQx7nbdRvkjGCEQgVjVtVwsHvV8NmV2a8xzQVwuFA"));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn block_stat(&self, hash: &str) -> AsyncResponse<response::BlockStatResponse> {
         self.request(&request::BlockStat { hash }, None)
@@ -427,6 +587,23 @@ impl IpfsClient {
 
     /// Add default peers to the bootstrap list.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.bootstrap_add_default());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn bootstrap_add_default(&self) -> AsyncResponse<response::BootstrapAddDefaultResponse> {
         self.request(&request::BootstrapAddDefault, None)
@@ -434,6 +611,23 @@ impl IpfsClient {
 
     /// Lists peers in bootstrap list.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.bootstrap_list());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn bootstrap_list(&self) -> AsyncResponse<response::BootstrapListResponse> {
         self.request(&request::BootstrapList, None)
@@ -441,6 +635,23 @@ impl IpfsClient {
 
     /// Removes all peers in bootstrap list.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.bootstrap_rm_all());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn bootstrap_rm_all(&self) -> AsyncResponse<response::BootstrapRmAllResponse> {
         self.request(&request::BootstrapRmAll, None)
@@ -448,6 +659,26 @@ impl IpfsClient {
 
     /// Returns the contents of an Ipfs object.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # extern crate futures;
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use futures::stream::Stream;
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    /// let hash = "QmXdNSQx7nbdRvkjGCEQgVjVtVwsHvV8NmV2a8xzQVwuFA";
+    ///
+    /// core.run(client.cat(hash).concat2());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn cat(&self, path: &str) -> AsyncStreamResponse<Chunk> {
         self.request_stream_bytes(&request::Cat { path }, None)
@@ -455,6 +686,21 @@ impl IpfsClient {
 
     /// List available commands that the server accepts.
     ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.commands());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn commands(&self) -> AsyncResponse<response::CommandsResponse> {
         self.request(&request::Commands, None)
@@ -462,6 +708,21 @@ impl IpfsClient {
 
     /// Opens the config file for editing (on the server).
     ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.config_edit());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn config_edit(&self) -> AsyncResponse<response::ConfigEditResponse> {
         self.request(&request::ConfigEdit, None)
@@ -469,6 +730,23 @@ impl IpfsClient {
 
     /// Replace the config file.
     ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use std::io::Cursor;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    /// let config = Cursor::new("{..json..}");
+    ///
+    /// core.run(client.config_replace(config));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn config_replace<R>(&self, data: R) -> AsyncResponse<response::ConfigReplaceResponse>
     where
@@ -485,6 +763,21 @@ impl IpfsClient {
     ///
     /// Returns an unparsed json string, due to an unclear spec.
     ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.config_show());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn config_show(&self) -> AsyncResponse<response::ConfigShowResponse> {
         self.request_string(&request::ConfigShow, None)
@@ -492,6 +785,21 @@ impl IpfsClient {
 
     /// Returns information about a dag node in Ipfs.
     ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.dag_get("QmXdNSQx7nbdRvkjGCEQgVjVtVwsHvV8NmV2a8xzQVwuFA"));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn dag_get(&self, path: &str) -> AsyncResponse<response::DagGetResponse> {
         self.request(&request::DagGet { path }, None)
@@ -516,6 +824,24 @@ impl IpfsClient {
 
     /// Query the DHT for all of the multiaddresses associated with a Peer ID.
     ///
+    /// ```
+    /// # extern crate futures;
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use futures::stream::Stream;
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    /// let peer = "QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM";
+    ///
+    /// core.run(client.dht_findpeer(peer).collect());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn dht_findpeer(&self, peer: &str) -> AsyncStreamResponse<response::DhtFindPeerResponse> {
         self.request_stream(&request::DhtFindPeer { peer }, None)
@@ -523,6 +849,24 @@ impl IpfsClient {
 
     /// Find peers in the DHT that can provide a specific value given a key.
     ///
+    /// ```
+    /// # extern crate futures;
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use futures::stream::Stream;
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    /// let key = "QmXdNSQx7nbdRvkjGCEQgVjVtVwsHvV8NmV2a8xzQVwuFA";
+    ///
+    /// core.run(client.dht_findprovs(key).collect());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn dht_findprovs(&self, key: &str) -> AsyncStreamResponse<response::DhtFindProvsResponse> {
         self.request_stream(&request::DhtFindProvs { key }, None)
@@ -530,6 +874,24 @@ impl IpfsClient {
 
     /// Query the DHT for a given key.
     ///
+    /// ```
+    /// # extern crate futures;
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use futures::stream::Stream;
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    /// let key = "QmXdNSQx7nbdRvkjGCEQgVjVtVwsHvV8NmV2a8xzQVwuFA";
+    ///
+    /// core.run(client.dht_get(key).collect());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn dht_get(&self, key: &str) -> AsyncStreamResponse<response::DhtGetResponse> {
         self.request_stream(&request::DhtGet { key }, None)
@@ -537,6 +899,24 @@ impl IpfsClient {
 
     /// Announce to the network that you are providing a given value.
     ///
+    /// ```
+    /// # extern crate futures;
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use futures::stream::Stream;
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    /// let key = "QmXdNSQx7nbdRvkjGCEQgVjVtVwsHvV8NmV2a8xzQVwuFA";
+    ///
+    /// core.run(client.dht_provide(key).collect());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn dht_provide(&self, key: &str) -> AsyncStreamResponse<response::DhtProvideResponse> {
         self.request_stream(&request::DhtProvide { key }, None)
@@ -544,6 +924,23 @@ impl IpfsClient {
 
     /// Write a key/value pair to the DHT.
     ///
+    /// ```
+    /// # extern crate futures;
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use futures::stream::Stream;
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.dht_put("test", "Hello World!").collect());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn dht_put(&self, key: &str, value: &str) -> AsyncStreamResponse<response::DhtPutResponse> {
         self.request_stream(&request::DhtPut { key, value }, None)
@@ -551,6 +948,24 @@ impl IpfsClient {
 
     /// Find the closest peer given the peer ID by querying the DHT.
     ///
+    /// ```
+    /// # extern crate futures;
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use futures::stream::Stream;
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    /// let peer = "QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM";
+    ///
+    /// core.run(client.dht_query(peer).collect());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn dht_query(&self, peer: &str) -> AsyncStreamResponse<response::DhtQueryResponse> {
         self.request_stream(&request::DhtQuery { peer }, None)
@@ -558,6 +973,21 @@ impl IpfsClient {
 
     /// Clear inactive requests from the log.
     ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.diag_cmds_clear());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn diag_cmds_clear(&self) -> AsyncResponse<response::DiagCmdsClearResponse> {
         self.request_empty(&request::DiagCmdsClear, None)
@@ -565,6 +995,21 @@ impl IpfsClient {
 
     /// Set how long to keep inactive requests in the log.
     ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.diag_cmds_set_time("1m"));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn diag_cmds_set_time(
         &self,
@@ -579,6 +1024,21 @@ impl IpfsClient {
     /// It might be platform dependent, but if it isn't, this can be fixed to return
     /// an actual object.
     ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.diag_sys());
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn diag_sys(&self) -> AsyncResponse<response::DiagSysResponse> {
         self.request_string(&request::DiagSys, None)
@@ -586,6 +1046,21 @@ impl IpfsClient {
 
     /// Resolve DNS link.
     ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.dns("ipfs.io", true));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn dns(&self, link: &str, recursive: bool) -> AsyncResponse<response::DnsResponse> {
         self.request(&request::Dns { link, recursive }, None)
@@ -593,6 +1068,21 @@ impl IpfsClient {
 
     /// List directory for Unix filesystem objects.
     ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.file_ls("/ipns/ipfs.io"));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn file_ls(&self, path: &str) -> AsyncResponse<response::FileLsResponse> {
         self.request(&request::FileLs { path }, None)
@@ -600,6 +1090,21 @@ impl IpfsClient {
 
     /// Copy files into MFS.
     ///
+    /// ```
+    /// # extern crate ipfs_api;
+    /// # extern crate tokio_core;
+    /// #
+    /// use ipfs_api::IpfsClient;
+    /// use tokio_core::reactor::Core;
+    ///
+    /// # fn main() {
+    /// let mut core = Core::new().unwrap();
+    /// let client = IpfsClient::default(&core.handle());
+    ///
+    /// core.run(client.files_cp("/path/to/file", "/dest"));
+    /// # }
+    /// ```
+    ///
     #[inline]
     pub fn files_cp(&self, path: &str, dest: &str) -> AsyncResponse<response::FilesCpResponse> {
         self.request_empty(&request::FilesCp { path, dest }, None)
diff --git a/ipfs-api/src/header.rs b/ipfs-api/src/header.rs
index 486be0c..460af2b 100644
--- a/ipfs-api/src/header.rs
+++ b/ipfs-api/src/header.rs
@@ -11,8 +11,16 @@ use hyper::header::{self, Header, Raw};
 use std::fmt;
 
 
+/// Header that is returned for streaming calls.
+///
+/// A `Trailer` header indicates that after a streaming call, there will
+/// be some additional information in the response.
+///
 #[derive(Debug, Clone, Copy)]
 pub enum Trailer {
+    /// This trailer indicates that an error header will be returned in
+    /// the stream if there is an error while streaming.
+    ///
     StreamError,
 }
 
@@ -44,6 +52,9 @@ impl Header for Trailer {
 }
 
 
+/// This header is included while streaming if an error occured
+/// while streaming the data.
+///
 #[derive(Debug, Clone)]
 pub struct XStreamError {
     pub error: String,