Merge #409

409: Improve documentation of public methods  r=niklaslong a=niklaslong

This PR goes some way towards improving the documentation of public methods as discussed in #197. 

Co-authored-by: Niklas Long <[email protected]>

src/p2p/addr.rs

@@ -82,7 +82,9 @@ impl FromStr for MultiaddrWithoutPeerId {
 /// don't support it being contained within the `Multiaddr`.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct MultiaddrWithPeerId {
+    /// The [`Multiaddr`] without the [`Protocol::P2p`] suffix.
     pub multiaddr: MultiaddrWithoutPeerId,
+    /// The peer id from the [`Protocol::P2p`] suffix.
     pub peer_id: PeerId,
 }
 

src/p2p/mod.rs

@@ -17,13 +17,20 @@ mod transport;
 pub use addr::{MultiaddrWithPeerId, MultiaddrWithoutPeerId};
 pub use {behaviour::KadResult, swarm::Connection};
 
+/// Type alias for [`libp2p::Swarm`] running the [`behaviour::Behaviour`] with the given [`IpfsTypes`].
 pub type TSwarm<T> = Swarm<behaviour::Behaviour<T>>;
 
+/// Defines the configuration for an IPFS swarm.
 pub struct SwarmOptions {
+    /// The keypair for the PKI based identity of the local node.
     pub keypair: Keypair,
+    /// The peer address of the local node created from the keypair.
     pub peer_id: PeerId,
+    /// The peers to connect to on startup.
     pub bootstrap: Vec<(Multiaddr, PeerId)>,
+    /// Enables mdns for peer discovery and announcement when true.
     pub mdns: bool,
+    /// Custom Kademlia protocol name, see [`IpfsOptions::kad_protocol`].
     pub kad_protocol: Option<String>,
 }
 

src/p2p/swarm.rs

@@ -15,7 +15,7 @@ use std::time::Duration;
 pub struct Connection {
     /// The connected peer along with its address.
     pub addr: MultiaddrWithPeerId,
-    /// Latest ping report on any of the connections
+    /// Latest ping report on any of the connections.
     pub rtt: Option<Duration>,
 }
 

src/path.rs

@@ -75,13 +75,15 @@ impl FromStr for IpfsPath {
 }
 
 impl IpfsPath {
+    /// Creates a new [`IpfsPath`] from a [`PathRoot`].
     pub fn new(root: PathRoot) -> Self {
         IpfsPath {
             root,
             path: Default::default(),
         }
     }
 
+    /// Returns the [`PathRoot`] "protocol" configured for the [`IpfsPath`].
     pub fn root(&self) -> &PathRoot {
         &self.root
     }
@@ -99,7 +101,7 @@ impl IpfsPath {
         Ok(path)
     }
 
-    /// Returns an iterator over the path segments following the root
+    /// Returns an iterator over the path segments following the root.
     pub fn iter(&self) -> impl Iterator<Item = &str> {
         self.path.iter().map(|s| s.as_str())
     }
@@ -259,6 +261,7 @@ impl fmt::Debug for PathRoot {
 }
 
 impl PathRoot {
+    /// Returns the `Some(Cid)` if the [`Cid`] based path is present or `None`.
     pub fn cid(&self) -> Option<&Cid> {
         match self {
             PathRoot::Ipld(cid) => Some(cid),