docs: add TSDoc comments interface-internal module (#2949)

Closes #2113

---------

Co-authored-by: Chad Nehemiah <[email protected]>
Co-authored-by: Alex Potsides <[email protected]>

Author: 3 people

packages/interface-internal/src/address-manager.ts

@@ -57,49 +57,66 @@ export interface ConfirmAddressOptions {
   type?: AddressType
 }
 
+/**
+ * The `AddressManager` provides an interface for managing peer addresses
+ * in libp2p. It supports handling multiple types of addresses, verifying their validity,
+ * and storing mappings between internal and external addresses.
+ */
 export interface AddressManager {
   /**
    * Get peer listen multiaddrs
+   * @returns An array of `Multiaddr` objects representing listen addresses.
    */
   getListenAddrs(): Multiaddr[]
 
   /**
    * Get peer announcing multiaddrs
+   * @returns An array of `Multiaddr` objects representing announce addresses.
    */
   getAnnounceAddrs(): Multiaddr[]
 
   /**
    * Get observed multiaddrs - these addresses may not have been confirmed as
    * publicly dialable yet
+   * @returns An array of `Multiaddr` objects representing observed addresses.
    */
   getObservedAddrs(): Multiaddr[]
 
   /**
    * Signal that we have confidence an observed multiaddr is publicly dialable -
    * this will make it appear in the output of getAddresses()
+   * 
+   * @param addr - The observed address.
+   * @param options - Additional options for confirmation.
    */
   confirmObservedAddr(addr: Multiaddr, options?: ConfirmAddressOptions): void
 
   /**
    * Signal that we do not have confidence an observed multiaddr is publicly dialable -
    * this will remove it from the output of getObservedAddrs()
+   * 
+   * @param addr - The observed address to remove.
    */
   removeObservedAddr(addr: Multiaddr): void
 
   /**
    * Add peer observed addresses.  These will then appear in the output of getObservedAddrs
    * but not getAddresses() until their dialability has been confirmed via a call to
    * confirmObservedAddr.
+   * 
+   * @param addr - The observed address to add.
    */
   addObservedAddr(addr: Multiaddr): void
 
   /**
    * Get the current node's addresses
+   * @returns An array of `Multiaddr` objects representing node addresses.
    */
   getAddresses(): Multiaddr[]
 
   /**
    * Return all known addresses with metadata
+   * @returns An array of `NodeAddress` objects.
    */
   getAddressesWithMetadata(): NodeAddress[]
 
@@ -108,11 +125,16 @@ export interface AddressManager {
    * `getAddresses` is invoked, where the IP addresses are present in a
    * multiaddr, an additional multiaddr will be added with `ip4` and `ip6`
    * tuples replaced with `dns4` and `dns6 ones respectively.
+   * 
+   * @param domain - The domain name to map.
+   * @param ipAddresses - The associated IP addresses.
    */
   addDNSMapping(domain: string, ipAddresses: string[]): void
 
   /**
    * Remove a mapping previously added with `addDNSMapping`.
+   * 
+   * @param domain - The domain name mapping to remove.
    */
   removeDNSMapping(domain: string): void
 
@@ -125,11 +147,23 @@ export interface AddressManager {
    * It's possible to add a IPv6 address here and have it added to the address
    * list, this is for the case when a router has an external IPv6 address with
    * port forwarding configured, but it does IPv6 -> IPv4 NAT.
+   * 
+   * @param internalIp - The internal IP address.
+   * @param internalPort - The internal port number.
+   * @param externalIp - The external IP address.
+   * @param externalPort - The external port number (optional).
+   * @param protocol - The transport protocol (`tcp` or `udp`).
    */
   addPublicAddressMapping (internalIp: string, internalPort: number, externalIp: string, externalPort?: number, protocol?: 'tcp' | 'udp'): void
 
   /**
    * Remove a publicly routable address that this node is no longer reachable on
+   * 
+   * @param internalIp - The internal IP address.
+   * @param internalPort - The internal port number.
+   * @param externalIp - The external IP address.
+   * @param externalPort - The external port number (optional).
+   * @param protocol - The transport protocol (`tcp` or `udp`).
    */
   removePublicAddressMapping (internalIp: string, internalPort: number, externalIp: string, externalPort?: number, protocol?: 'tcp' | 'udp'): void
 }

packages/interface-internal/src/connection-manager.ts

@@ -3,6 +3,9 @@ import type { PeerMap } from '@libp2p/peer-collections'
 import type { Multiaddr } from '@multiformats/multiaddr'
 import type { ProgressOptions } from 'progress-events'
 
+/**
+ * Options for opening a connection to a remote peer.
+ */
 export interface OpenConnectionOptions extends AbortOptions, ProgressOptions<OpenConnectionProgressEvents> {
   /**
    * Connection requests with a higher priority will be executed before those
@@ -34,49 +37,49 @@ export interface OpenConnectionOptions extends AbortOptions, ProgressOptions<Ope
   initiator?: boolean
 }
 
+/**
+ * The `ConnectionManager` handles managing connections between peers in a libp2p network.
+ * It provides methods for opening, closing, and querying connections.This also provides methods
+ * for accessing the dial queue.
+ */
 export interface ConnectionManager {
   /**
    * Return connections, optionally filtering by a PeerId
    *
-   * @example
-   *
-   * ```TypeScript
-   * const connections = libp2p.connectionManager.get(peerId)
-   * // []
-   * ```
+   * @param peerId - The PeerId to filter connections (optional).
+   * @returns An array of active `Connection` objects.
    */
   getConnections(peerId?: PeerId): Connection[]
 
   /**
    * Return a map of all connections with their associated PeerIds
    *
-   * @example
-   *
-   * ```TypeScript
-   * const connectionsMap = libp2p.connectionManager.getConnectionsMap()
-   * ```
+   * @returns A `PeerMap` containing `Connection[]` objects.
    */
   getConnectionsMap(): PeerMap<Connection[]>
 
   /**
    * Returns the configured maximum number of connections this connection
    * manager will accept
+   * @returns The maximum connection limit.
    */
   getMaxConnections(): number
 
   /**
    * Open a connection to a remote peer
    *
-   * @example
-   *
-   * ```TypeScript
-   * const connection = await libp2p.connectionManager.openConnection(peerId)
-   * ```
+   * @param peer - The target `PeerId`, `Multiaddr`, or an array of `Multiaddr`s.
+   * @param options - Optional parameters for connection handling.
+   * @returns A promise that resolves to a `Connection` object.
    */
   openConnection(peer: PeerId | Multiaddr | Multiaddr[], options?: OpenConnectionOptions): Promise<Connection>
 
   /**
    * Close our connections to a peer
+   * 
+   * @param peer - The `PeerId` whose connections should be closed.
+   * @param options - Optional abort options.
+   * @returns A promise that resolves once the connections are closed.
    */
   closeConnections(peer: PeerId, options?: AbortOptions): Promise<void>
 
@@ -85,6 +88,9 @@ export interface ConnectionManager {
    * exchanged, this lets the ConnectionManager check we have sufficient
    * resources to accept the connection in which case it will return true,
    * otherwise it will return false.
+   * 
+   * @param maConn - The multiaddr connection to evaluate.
+   * @returns A promise that resolves to `true` if the connection can be accepted, `false` otherwise.
    */
   acceptIncomingConnection(maConn: MultiaddrConnection): Promise<boolean>
 
@@ -96,11 +102,7 @@ export interface ConnectionManager {
   /**
    * Return the list of in-progress or queued dials
    *
-   * @example
-   *
-   * ```TypeScript
-   * const dials = libp2p.connectionManager.getDialQueue()
-   * ```
+   * @returns An array of `PendingDial` objects.
    */
   getDialQueue(): PendingDial[]
 
@@ -112,6 +114,9 @@ export interface ConnectionManager {
    * would not block the dial attempt.
    *
    * This may involve resolving DNS addresses so you should pass an AbortSignal.
+   * @param multiaddr - The target multiaddr or an array of multiaddrs.
+   * @param options - Optional parameters for dialability check.
+   * @returns A promise that resolves to `true` if the multiaddr is dialable, `false` otherwise.
    */
   isDialable(multiaddr: Multiaddr | Multiaddr[], options?: IsDialableOptions): Promise<boolean>
 }

packages/interface-internal/src/index.ts

@@ -1,3 +1,13 @@
+/**
+ * @packageDocumentation
+ *
+ * This module serves as the entry point for `@libp2p/interface-internal`,
+ * re-exporting key components such as `AddressManager`, `ConnectionManager`, 
+ * `RandomWalk`, `Registrar`, and `TransportManager`.
+ *
+ * These interfaces and classes define the core internal behaviors of libp2p.
+ */
+
 export * from './address-manager.js'
 export * from './connection-manager.js'
 export * from './random-walk.js'

packages/interface-internal/src/random-walk.ts

@@ -1,13 +1,21 @@
 import type { AbortOptions, PeerInfo } from '@libp2p/interface'
 
 /**
- * RandomWalk finds random peers on the network and dials them. Use this after
- * registering a Topology if you need to discover common network services.
+ * The `RandomWalk` component uses the libp2p peer routing to find arbitrary
+ * network peers. Consumers may then dial these peers, causing the Identify
+ * protocol to run and any registered topologies to be notified of their
+ * supported protocols.
  */
 export interface RandomWalk {
   /**
-   * Begin or join an existing walk. Abort the passed signal if you wish to
-   * abort the walk early.
+   * Initiates a random walk for peer discovery.
+   *
+   * This method either begins a new random walk or joins an existing one. The process 
+   * continues to find and return random peers until it is aborted.
+   *
+   * @param options - Optional `AbortOptions` to allow early termination of the walk.
+   * @returns An `AsyncGenerator` that yields discovered `PeerInfo` objects.
+   *
    */
   walk(options?: AbortOptions): AsyncGenerator<PeerInfo>
 }

packages/interface-internal/src/registrar.ts

@@ -22,24 +22,49 @@ export type {
   StreamHandlerRecord
 }
 
+/**
+ * The `Registrar` provides an interface for registering protocol handlers -
+ * these are invoked when remote peers open streams on the local node with the
+ * corresponding protocol name.
+ *
+ * It also allows configuring network topologies for a given protocol(s). The
+ * topology callbacks are invoked when a peer that supports those protocols
+ * connects or disconnects.
+ *
+ * The Identify protocol must be configured on the current node for topologies
+ * to function.
+ */
 export interface Registrar {
   /**
-   * Return the list of protocols with registered handlers
+   * Retrieve the list of registered protocol handlers.
+   *
+   * @returns An array of protocol strings.
    */
   getProtocols(): string[]
 
   /**
-   * Add a protocol handler
+   * Register a handler for a specific protocol.
+   *
+   * @param protocol - The protocol string (e.g., `/my-protocol/1.0.0`).
+   * @param handler - The function that handles incoming streams.
+   * @param options - Optional configuration options for the handler.
+   * @returns A promise that resolves once the handler is registered.
    */
   handle(protocol: string, handler: StreamHandler, options?: StreamHandlerOptions): Promise<void>
 
   /**
-   * Remove a protocol handler
+   * Remove a registered protocol handler.
+   *
+   * @param protocol - The protocol to unhandle.
+   * @returns A promise that resolves once the handler is removed.
    */
   unhandle(protocol: string): Promise<void>
 
   /**
-   * Return the handler for the passed protocol
+   * Retrieve the registered handler for a given protocol.
+   *
+   * @param protocol - The protocol to query.
+   * @returns A `StreamHandlerRecord` containing the handler and options.
    */
   getHandler(protocol: string): StreamHandlerRecord
 
@@ -50,17 +75,26 @@ export interface Registrar {
    *
    * An id will be returned that can later be used to unregister the
    * topology.
+   * 
+   * @param protocol - The protocol to register.
+   * @param topology - The topology handler to register.
+   * @returns A promise resolving to a unique ID for the registered topology.
    */
   register(protocol: string, topology: Topology): Promise<string>
 
   /**
-   * Remove the topology handler with the passed id.
+   * Unregister a topology handler using its unique ID.
+   *
+   * @param id - The ID of the topology to unregister.
    */
   unregister(id: string): void
 
   /**
-   * Return all topology handlers that wish to be informed about peers
-   * that support the passed protocol.
+   * Retrieve all topology handlers that are interested in peers
+   * supporting a given protocol.
+   *
+   * @param protocol - The protocol to query.
+   * @returns An array of registered `Topology` handlers.
    */
   getTopologies(protocol: string): Topology[]
 }