From 9b0b950414fbde2170a00220b8aa2ea6fd8860d2 Mon Sep 17 00:00:00 2001 From: Ferris Tseng Date: Thu, 30 Nov 2017 23:18:21 -0500 Subject: add documentation --- ipfs-api/src/client.rs | 507 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 506 insertions(+), 1 deletion(-) (limited to 'ipfs-api/src/client.rs') 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 = Box>; @@ -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(&self, data: R) -> AsyncResponse 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 { 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 { 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 { 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 { 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(&self, data: R) -> AsyncResponse 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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(&self, data: R) -> AsyncResponse 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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 { self.request_empty(&request::FilesCp { path, dest }, None) -- cgit v1.2.3