chore: add notice for addressBook.set

Author: vasco-santos

doc/API.md

@@ -814,7 +814,8 @@ peerStore.addressBook.getMultiaddrsForPeer(peerId)
 
 ### peerStore.addressBook.set
 
-Set known `multiaddrs` of a given peer.
+Set known `multiaddrs` of a given peer. This will replace previously stored multiaddrs, if available.
+Replacing stored multiaddrs might result in losing obtained certified addresses, which is not desirable.
 
 `peerStore.addressBook.set(peerId, multiaddrs)`
 

src/peer-store/address-book.js

@@ -158,6 +158,8 @@ class AddressBook extends Book {
 
   /**
    * Set known multiaddrs of a provided peer.
+   * This will replace previously stored multiaddrs, if available.
+   * Replacing stored multiaddrs might result in losing obtained certified addresses.
    * @override
    * @param {PeerId} peerId
    * @param {Array<Multiaddr>} multiaddrs