docs: update comments in interface module and elsewhere (#3107)

Fixes #2112

Author: achingbrain

packages/config/README.md

@@ -24,6 +24,8 @@ repo and examine the changes made.
 
 -->
 
+Utilities to make working with libp2p configuration simpler.
+
 ## Example - Load or create the "self" private key in a datastore
 
 Most nodes will want to persist the same private key between restarts so this
@@ -33,7 +35,7 @@ will create a new one and save it in the keystore.
 The options you pass to this function should be the same as those passed to
 the `@libp2p/keychain` service you configure your node with.
 
-```ts
+```TypeScript
 import { loadOrCreateSelfKey } from '@libp2p/config'
 import { keychain } from '@libp2p/keychain'
 import { LevelDatastore } from 'datastore-level'

packages/config/src/index.ts

@@ -1,6 +1,8 @@
 /**
  * @packageDocumentation
  *
+ * Utilities to make working with libp2p configuration simpler.
+ *
  * @example Load or create the "self" private key in a datastore
  *
  * Most nodes will want to persist the same private key between restarts so this
@@ -10,7 +12,7 @@
  * The options you pass to this function should be the same as those passed to
  * the `@libp2p/keychain` service you configure your node with.
  *
- * ```ts
+ * ```TypeScript
  * import { loadOrCreateSelfKey } from '@libp2p/config'
  * import { keychain } from '@libp2p/keychain'
  * import { LevelDatastore } from 'datastore-level'

packages/connection-encrypter-plaintext/README.md

@@ -24,9 +24,10 @@ repo and examine the changes made.
 
 -->
 
-A connection encrypter that does no connection encryption.
+A connection encrypter that does no connection encryption and trusts the
+remote peer to provide the correct PeerId.
 
-This should not be used in production should be used for research purposes only.
+This should not be used in production and is for research purposes only.
 
 ## Example
 

packages/connection-encrypter-plaintext/src/index.ts

@@ -1,9 +1,10 @@
 /**
  * @packageDocumentation
  *
- * A connection encrypter that does no connection encryption.
+ * A connection encrypter that does no connection encryption and trusts the
+ * remote peer to provide the correct PeerId.
  *
- * This should not be used in production should be used for research purposes only.
+ * This should not be used in production and is for research purposes only.
  *
  * @example
  *

packages/crypto/src/ciphers/aes-gcm.browser.ts

@@ -1,7 +1,7 @@
 import { concat } from 'uint8arrays/concat'
 import { fromString } from 'uint8arrays/from-string'
 import webcrypto from '../webcrypto/index.js'
-import type { CreateOptions, AESCipher } from './interface.js'
+import type { CreateAESCipherOptions, AESCipher } from './interface.js'
 
 // WebKit on Linux does not support deriving a key from an empty PBKDF2 key.
 // So, as a workaround, we provide the generated key as a constant. We test that
@@ -24,7 +24,7 @@ export const derivedEmptyPasswordKey = {
 
 // Based off of code from https://github.com/luke-park/SecureCompatibleEncryptionExamples
 
-export function create (opts?: CreateOptions): AESCipher {
+export function create (opts?: CreateAESCipherOptions): AESCipher {
   const algorithm = opts?.algorithm ?? 'AES-GCM'
   let keyLength = opts?.keyLength ?? 16
   const nonceLength = opts?.nonceLength ?? 12

packages/crypto/src/ciphers/aes-gcm.ts

@@ -1,11 +1,13 @@
 import crypto from 'crypto'
 import { concat as uint8ArrayConcat } from 'uint8arrays/concat'
 import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
-import type { CreateOptions, AESCipher } from './interface.js'
+import type { CreateAESCipherOptions, AESCipher } from './interface.js'
+
+export type { AESCipher, CreateAESCipherOptions }
 
 // Based off of code from https://github.com/luke-park/SecureCompatibleEncryptionExamples
 
-export function create (opts?: CreateOptions): AESCipher {
+export function create (opts?: CreateAESCipherOptions): AESCipher {
   const algorithm = opts?.algorithm ?? 'aes-128-gcm'
   const keyLength = opts?.keyLength ?? 16
   const nonceLength = opts?.nonceLength ?? 12

packages/crypto/src/ciphers/interface.ts

@@ -1,4 +1,4 @@
-export interface CreateOptions {
+export interface CreateAESCipherOptions {
   algorithm?: string
   nonceLength?: number
   keyLength?: number

packages/interface-compliance-tests/src/matchers.ts

@@ -1,17 +1,18 @@
 import Sinon from 'sinon'
 import type { PeerId } from '@libp2p/interface'
 import type { Multiaddr } from '@multiformats/multiaddr'
+import type { SinonMatcher } from 'sinon'
 
 /**
  * @deprecated PeerIds can be passed to sinon matchers directly
  */
-export function matchPeerId (peerId: PeerId): Sinon.SinonMatcher {
+export function matchPeerId (peerId: PeerId): SinonMatcher {
   return Sinon.match(p => p.toString() === peerId.toString())
 }
 
 /**
  * @deprecated Multiaddrs can be passed to sinon matchers directly
  */
-export function matchMultiaddr (ma: Multiaddr): Sinon.SinonMatcher {
+export function matchMultiaddr (ma: Multiaddr): SinonMatcher {
   return Sinon.match(m => m.toString() === ma.toString())
 }

packages/interface/src/content-routing.ts

@@ -4,7 +4,7 @@ import type { CID } from 'multiformats/cid'
 
 /**
  * Any object that implements this Symbol as a property should return a
- * ContentRouting instance as the property value, similar to how
+ * Partial<ContentRouting> instance as the property value, similar to how
  * `Symbol.Iterable` can be used to return an `Iterable` from an `Iterator`.
  *
  * @example
@@ -28,7 +28,7 @@ export const contentRoutingSymbol = Symbol.for('@libp2p/content-routing')
  * interested callers.
  */
 export interface ContentRoutingProvider {
-  [contentRoutingSymbol]: ContentRouting
+  [contentRoutingSymbol]: Partial<ContentRouting>
 }
 
 export interface ContentRouting {

packages/interface/src/errors.ts

@@ -353,7 +353,7 @@ export class TooManyOutboundProtocolStreamsError extends Error {
 }
 
 /**
- * Thrown when and attempt to operate on an unsupported key was made
+ * Thrown when an attempt to operate on an unsupported key was made
  */
 export class UnsupportedKeyTypeError extends Error {
   static name = 'UnsupportedKeyTypeError'
@@ -363,3 +363,15 @@ export class UnsupportedKeyTypeError extends Error {
     this.name = 'UnsupportedKeyTypeError'
   }
 }
+
+/**
+ * Thrown when an operation has not been implemented
+ */
+export class NotImplementedError extends Error {
+  static name = 'NotImplementedError'
+
+  constructor (message = 'Not implemented') {
+    super(message)
+    this.name = 'NotImplementedError'
+  }
+}

packages/interface/src/event-target.ts

@@ -10,7 +10,8 @@ interface Listener {
 }
 
 /**
- * Adds types to the EventTarget class. Hopefully this won't be necessary forever.
+ * Adds types to the EventTarget class. Hopefully this won't be necessary
+ * forever.
  *
  * https://github.com/microsoft/TypeScript/issues/28357
  * https://github.com/microsoft/TypeScript/issues/43477
@@ -31,7 +32,6 @@ export interface TypedEventTarget <EventMap extends Record<string, any>> extends
 
 /**
  * An implementation of a typed event target
- * etc
  */
 export class TypedEventEmitter<EventMap extends Record<string, any>> extends EventTarget implements TypedEventTarget<EventMap> {
   readonly #listeners = new Map<any, Listener[]>()

packages/interface/src/index.ts

@@ -53,6 +53,9 @@ export interface SignedPeerRecord {
   seq: bigint
 }
 
+/**
+ * A certificate that can be used to secure connections
+ */
 export interface TLSCertificate {
   /**
    * The private key that corresponds to the certificate in PEM format
@@ -130,9 +133,43 @@ export interface Logger {
 }
 
 /**
- * Peer logger component for libp2p
+ * Peer logger component for libp2p. This can be used to create loggers that are
+ * scoped to individual system components or services.
+ *
+ * To see logs, run your app with `DEBUG` set as an env var or for browsers, in
+ * `localStorage`:
+ *
+ * ```console
+ * $ DEBUG=libp2p* node index.js
+ *  libp2p:my-service hello +0ms
+ * ```
  */
 export interface ComponentLogger {
+  /**
+   * Returns a logger for the specified component.
+   *
+   * @example
+   *
+   * ```TypeScript
+   * import { ComponentLogger, Logger } from '@libp2p/interface'
+   *
+   * interface MyServiceComponents {
+   *   logger: ComponentLogger
+   * }
+   *
+   * class MyService {
+   *   private readonly log: Logger
+   *
+   *   constructor (components) {
+   *     this.log = components.logger.forComponent('libp2p:my-service')
+   *
+   *     this.log('hello')
+   *     // logs:
+   *     // libp2p:my-service hello +0ms
+   *   }
+   * }
+   * ```
+   */
   forComponent(name: string): Logger
 }
 

packages/interface/src/metrics.ts

@@ -510,7 +510,7 @@ export interface Metrics {
 /**
  * Infer the yielded type of an (async)iterable
  */
-type YieldType<T extends AsyncIterator<any> | Iterator<any>> = T extends AsyncIterator<infer Y> ? Y : T extends Iterator<infer Y, any, any> ? Y : never
+export type YieldType<T extends AsyncIterator<any> | Iterator<any>> = T extends AsyncIterator<infer Y> ? Y : T extends Iterator<infer Y, any, any> ? Y : never
 
 export type TraceAttributes = Record<string, number | string | boolean | number[] | string[] | boolean[]>
 

packages/interface/src/peer-discovery.ts

@@ -34,4 +34,9 @@ export interface PeerDiscoveryEvents {
   'peer': CustomEvent<PeerInfo>
 }
 
+/**
+ * A class that implements the `PeerDiscovery` interface uses an
+ * implementation-specific method to discover peers. These peers are then added
+ * to the peer store for use by other system components and services.
+ */
 export interface PeerDiscovery extends TypedEventTarget<PeerDiscoveryEvents> {}

packages/interface/src/peer-routing.ts

@@ -4,8 +4,8 @@ import type { PeerInfo } from './peer-info.js'
 
 /**
  * Any object that implements this Symbol as a property should return a
- * PeerRouting instance as the property value, similar to how
- * `Symbol.Iterable` can be used to return an `Iterable` from an `Iterator`.
+ * PeerRouting instance as the property value, similar to how `Symbol.Iterable`
+ * can be used to return an `Iterable` from an `Iterator`.
  *
  * @example
  *
@@ -28,7 +28,7 @@ export const peerRoutingSymbol = Symbol.for('@libp2p/peer-routing')
  * interested callers.
  */
 export interface PeerRoutingProvider {
-  [peerRoutingSymbol]: PeerRouting
+  [peerRoutingSymbol]: Partial<PeerRouting>
 }
 
 export interface PeerRouting {

packages/interface/src/pubsub.ts

@@ -153,6 +153,9 @@ export interface TopicValidatorFn {
   (peer: PeerId, message: Message): TopicValidatorResult | Promise<TopicValidatorResult>
 }
 
+/**
+ * @deprecated This will be removed from `@libp2p/interface` in a future release, pubsub implementations should declare their own types
+ */
 export interface PubSub<Events extends Record<string, any> = PubSubEvents> extends TypedEventTarget<Events> {
   /**
    * The global signature policy controls whether or not we sill send and receive

packages/interface/src/record.ts

@@ -23,13 +23,42 @@ export interface Record {
   equals(other: Record): boolean
 }
 
+/**
+ * A message with a signed payload.
+ */
 export interface Envelope {
+  /**
+   * The public key of the keypair used to sign the payload
+   */
   publicKey: PublicKey
+
+  /**
+   * How the payload should be interpreted
+   */
   payloadType: Uint8Array | Uint8ArrayList
+
+  /**
+   * The contents of the envelope
+   */
   payload: Uint8Array
+
+  /**
+   * A signature that can be used to verify the payload is intact
+   */
   signature: Uint8Array | Uint8ArrayList
 
+  /**
+   * Serialize the envelope to a binary format
+   */
   marshal(): Uint8Array
+
+  /**
+   * Use the public key to validate that the payload is intact
+   */
   validate(domain: string): Promise<boolean>
-  equals(other: Envelope): boolean
+
+  /**
+   * Returns true if this envelope has equivalency with the passed object
+   */
+  equals(other?: Envelope): boolean
 }