docs: add TSDoc comments interface-internal module

[Khwahish29]

Title

docs: Add TSDoc comments to @libp2p/interface-internal (#2113 )

Description

This PR adds TSDoc comments to @libp2p/interface-internal, ensuring that all exported interfaces, types, and constants have proper documentation. This improves the generated API documentation and aligns with the project's documentation standards.

Notes & open questions

• Please review if the added examples align with best practices.
• Let me know if any additional clarifications are needed.

Change checklist

• I have performed a self-review of my own code
• I have made corresponding changes to the documentation if necessary (this includes comments as well)
• I have added tests that prove my fix is effective or that my feature works

[maschad]

Great work here @Khwahish29 . I've left some comments.

My personal opinion is that we don't need examples for the applicability these internal interfaces, but interested to see @achingbrain 's opinion.

[Khwahish29]

Great work here @Khwahish29 . I've left some comments.

My personal opinion is that we don't need examples for the applicability these internal interfaces, but interested to see @achingbrain 's opinion.

Hey @maschad! Took your feedback and updated the TSDoc comments for @libp2p/interface-internal

• Removed unnecessary examples.
• Cleaned up descriptions to keep things clear and consistent.

Really appreciate the thoughtful feedback! Let me know if there’s anything else to tweak. 🚀

[achingbrain]

I don't think we need @packageDocumentation tags for each file here.

From the docs:

Used to indicate a doc comment that describes an entire NPM package (as opposed to an individual API item belonging to that package)

The text from the @packageDocumentation tags you've added could be used in the tag describing the main interface exported from each file instead.

[Khwahish29]

Thanks for the clarification! 🙌
I’ve moved the @packageDocumentation tags. Let me know if this looks good or if there’s anything else to adjust!

[maschad]

Thanks for this @Khwahish29 this LGTM

[achingbrain]

Good stuff, comments inline.

I would definitely recommend running npm run docs and checking the generated output in the .docs folder as I think some of the changes here won't necessarily appear where you think they will (details are below).

[achingbrain]

This needs to be one comment, not two, otherwise only the second will appear in the generated docs.

You can check this by running npm run docs in the root of the repo and looking at the HTML that appears in the .docs folder.

Suggested change

	/**
	* The `AddressManager` module 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.
	*/
	/**
	* Interface for managing peer addresses in libp2p.
	*/
	export interface AddressManager {
	/**
	* 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 {

[achingbrain]

Must be a single comment, not two:

Suggested change

	/**
	* The `ConnectionManager` module 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.
	*/
	/**
	* Manages the dialing, opening, and closing of connections.
	*/
	/**
	* 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.
	*/

[achingbrain]

Must be a single comment, not two.

Also, the docs were wrong here - RandomWalk only discovers peers, it doesn't dial them.

Suggested change

	* The `RandomWalk` module facilitates peer discovery by randomly finding and dialing peers
	* on the libp2p network. It is useful in conjunction with a registered `Topology` to
	* discover common network services.
	*/
	/**
	* The `RandomWalk` interface provides a mechanism for discovering and connecting to
	* random peers on the libp2p network.
	* 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.

[achingbrain]

I'm not sure this comment is necessary - these are named exports so will get their own documentation blocks.

Please can you check the output of npm run docs (look in the .docs folder) and delete this comment if it doesn't appear anywhere.

[achingbrain]

Must be a single comment, not two.

Also we can be a bit more specific in the comment:

Suggested change

	/**
	* The `Registrar` module provides an interface for managing protocol handlers
	* and topologies in a libp2p network. It enables registering and managing
	* protocol-specific handlers, ensuring efficient peer-to-peer communication.
	*/
	/**
	* The `Registrar` interface allows modules to register, manage, and remove
	* protocol handlers and topology discovery mechanisms in libp2p.
	*/
	/**
	* 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.
	*/

[achingbrain]

This part about the id being used to unregister the topology later is important, please do not delete it.

[achingbrain]

Must be a single comment, not two.

Also protocols is a loaded word here, since it is used to refer to protocol streams. Better to just call transports "transports" or "network transports" and not "transport protocols".

Also, also, it's probably worth noting that consumers should generally prefer to open connections using the connection manager.

Suggested change

	/**
	* The `TransportManager` module handles the management of transport protocols in a libp2p network.
	* It is responsible for managing the transport themselves - dialling, querying addresses and listening.
	*/
	/**
	* The `TransportManager` interface manages available transports for dialing and listening in a libp2p node.
	*/
	/**
	* The `TransportManager` handles the management of network transports, allowing
	* opening connections or listening using specific transports, etc.
	*
	* This is a low-level component - any connections opened will not be managed by
	* the `ConnectionManager` or included in any configured connection limits, etc.
	*
	* Most consumers will call `openConnection` on the `ConnectionManager` instead.
	*/

[Khwahish29]

@achingbrain I've addressed the latest round of feedback—please let me know if there's anything else that needs further improvement.
I truly appreciate the time and effort you’ve put into reviewing my work and ensuring it meets the right standards :)