diff --git a/README.md b/README.md
index 2a37fe75..56b4f177 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@ js-multiaddr <!-- omit in toc -->
 
 - [Background](#background)
   - [What is multiaddr?](#what-is-multiaddr)
+- [Migrate to 0.9](#migrate-to-09)
 - [Install](#install)
   - [NPM](#npm)
   - [Browser: `<script>` Tag](#browser-script-tag)
@@ -38,6 +39,45 @@ A standard way to represent addresses that
 - have a nice string representation
 - encapsulate well
 
+## Migrate to 0.9
+Before 0.9 `multiaddr` would return an constructor function.
+```js
+const multiaddr = require('multiaddr')
+
+const mh1 = multiaddr('/ip4/127.0.0.1/udp/1234')
+
+const mh2 = new multiaddr('/ip4/127.0.0.1/udp/1234')
+// both mh1 and mh2 were multiaddr instances
+
+multiaddr.isName()
+multiaddr.protocols
+// etc 
+
+```
+In 0.9 `multiaddr` returns a class.
+```js
+const Multiaddr = require('multiaddr')
+// you need to use `new` to create and instance
+const mh1 = new Multiaddr('/ip4/127.0.0.1/udp/1234') 
+```
+
+```js
+// The Multiaddr class has a factory method to help migration
+const { multiaddr } = require('multiaddr')
+
+const mh1 = multiaddr('/ip4/127.0.0.1/udp/1234')
+```
+```js
+// In case you are using the static methods/getters `fromNodeAddress`, `isName` , `isMultiaddr`, `protocols` and `resolvers`
+// You will need to do a couple more changes
+const Multiaddr = require('multiaddr')
+const { multiaddr, isName } = Multiaddr
+
+// multiaddr.isName() will not work anymore, only the default export has those methods/getters
+Multiaddr.isName() // or just `isName()`
+
+```
+
 ## Install
 
 ```sh
diff --git a/src/index.js b/src/index.js
index d57166d4..1450b411 100644
--- a/src/index.js
+++ b/src/index.js
@@ -12,7 +12,7 @@ const resolvers = new Map()
 const symbol = Symbol.for('@multiformats/js-multiaddr/multiaddr')
 
 /**
- * @typedef {import('./types').Protocol}Protocol
+ * @typedef {import('./types').Protocol} Protocol
  */
 
 /**
@@ -561,7 +561,7 @@ class Multiaddr {
    * Check if object is a CID instance
    *
    * @param {any} value
-   * @returns {boolean}
+   * @returns {value is Multiaddr}
    */
   static isMultiaddr (value) {
     return value instanceof Multiaddr || Boolean(value && value[symbol])