diff --git a/core/src/main/scala/fluence/multiaddr/Multiaddr.scala b/core/src/main/scala/fluence/multiaddr/Multiaddr.scala
index 3e259bd..6a83785 100644
--- a/core/src/main/scala/fluence/multiaddr/Multiaddr.scala
+++ b/core/src/main/scala/fluence/multiaddr/Multiaddr.scala
@@ -19,22 +19,55 @@ package fluence.multiaddr
 
 import fluence.multiaddr.Multiaddr.ErrorMessage
 
+/**
+  * Multiaddress representation by string and list of protocols.
+  */
 case class Multiaddr private(address: String, protoParameters: List[ProtoParameter]) {
+
   /**
-    * Wraps a given Multiaddr, returning the resulting joined Multiaddr.
+    * Encapsulates a Multiaddr in another Multiaddr.
     *
-    * @return new joined Multiaddr
+    * Spec about encapsulate:
+    * https://github.com/multiformats/multiaddr#encapsulation-based-on-context
+    *
+    * val m = Multiaddr("/ip4/127.0.0.1/tcp/1234")
+    * println(m.encapsulate(Multiaddr.unsafe("/sctp/5678")).right.get.address)
+    * "/ip4/127.0.0.1/tcp/1234/sctp/5678"
+    *
+    * @param addr Multiaddr to add into this Multiaddr
+    * @return new Multiaddr
     */
   def encapsulate(addr: Multiaddr): Either[ErrorMessage, Multiaddr] = Multiaddr(address + addr.address)
 
   /**
-    * Decapsulate unwraps Multiaddr up until the given Multiaddr is found.
+    * Decapsulates a Multiaddr from another Multiaddr.
+    *
+    * Spec about encapsulate and decapsulate:
+    * https://github.com/multiformats/multiaddr#encapsulation-based-on-context
+    *
+    * val m = Multiaddr("/ip4/127.0.0.1/tcp/1234/sctp/5678")
+    * println(m.decapsulate(Multiaddr.unsafe("/sctp/5678")).right.get.address)
+    * "/ip4/127.0.0.1/tcp/1234"
+    *
+    * @param addr Multiaddr to remove from this Multiaddr
     *
     * @return decapsulated Multiaddr
     */
   def decapsulate(addr: Multiaddr): Either[ErrorMessage, Multiaddr] = decapsulate(addr.address)
 
-
+  /**
+    * Possibility to decapsulate by part of address.
+    *
+    * Spec about encapsulate and decapsulate:
+    * https://github.com/multiformats/multiaddr#encapsulation-based-on-context
+    *
+    * val m = Multiaddr("/ip4/127.0.0.1/tcp/1234/sctp/5678")
+    * println(m.decapsulate("/sctp").right.get.address)
+    * "/ip4/127.0.0.1/tcp/1234"
+    *
+    * @param addr Multiaddr to remove from this Multiaddr
+    * @return decapsulated Multiaddr
+    */
   def decapsulate(addr: String): Either[ErrorMessage, Multiaddr] = {
     val lastIndex = address.lastIndexOf(addr)
     if (lastIndex < 0)
@@ -49,6 +82,9 @@ object Multiaddr {
 
   type ErrorMessage = String
 
+  /**
+    * Parse and validate multiaddr string.
+    */
   def apply(addr: String): Either[ErrorMessage, Multiaddr] = MultiaddrParser.parse(addr).map {
     case (trimmed, protoParameters) => new Multiaddr(trimmed, protoParameters)
   }