RFC: generated API docs from typescript declarations

[alanshaw]

I had an idea in #651 (comment) that we could add typescript declarations (i.e. not convert the project to typescript just a type delcarations file types.d.ts with typings information) and generate our documentation from them. It would give us incentive to keep them up to date and make js-ipfs more friendly to our community of typescript users!

The docs would be decoupled from the actual code but we already have that problem.

Maybe use http://typedoc.org/?

@carsonfarmer might have some ideas if this is possible and might want to be the one to PR the declarations 😝

refs #1166
refs #2320

[carsonfarmer]

This is very exciting to hear! I understand from @raulk that the libp2p team is similarly interested in adding declarations files to individual repos, which would likely make the efforts on js-ipfs much easier. I'm not sure what the timeline is for libp2p projects though?

We've used typedoc before (see https://textileio.github.io/js-textile-wallet/ for example) and quite liked it.

[hugomrdias]

I have been trying to push this for a long time, nice to know we are open to this now.
ipfsd-ctl already has some typedefs and the next version will have a lot more this is what makes this ipfs-inactive/interface-js-ipfs-core#541 (comment) possible.

Happy to make this happen huge improvement to DX

[alanshaw]

I'm somewhat disappointed with typedoc...

I added type definitions to abortable-iterator to try it out and was immediately burnt by TypeStrong/typedoc#1050:

When the "Only Exported" checkbox is checked the list on the right is incorrect. Where's my sink, transorm and duplex exports? Source code:

I also have a function called source and a type called Source. Clicking the links in the menu on the right do not work properly because it generates <a name="source" /> and <a name="Source" />.

For reference, my setup: alanshaw/abortable-iterator#2

[hugomrdias]

Why do you export source as default again? i stopped using default exports a long time ago it only gives you problems esm or no esm. https://humanwhocodes.com/blog/2019/01/stop-using-default-exports-javascript-module/

Below is a preview for the latest ipfsd-ctl api docs in markdown (still WIP)

Table of Contents

• create
  • Parameters
• createNode
  • Parameters
• createNodeTests
  • Parameters
• createTestsInterface
  • Parameters
• createServer
  • Parameters
• TestsInterfaceCreateNode
  • Parameters
• TestsInterfaceSetup
  • Parameters
• TestsInterfaceTeardown
• TestsInterface
  • Properties
• IpfsOptions
  • Properties
• FactoryOptions
  • Properties

create

src/index.js:34-41

Create a Factory

Parameters

• opts FactoryOptions (optional, default {})

Returns FactoryDaemon

createNode

src/index.js:49-57

Create a node

Parameters

• opts FactoryOptions (optional, default {})

Returns Promise<Daemon>

createNodeTests

src/index.js:65-88

Create a node for tests

Parameters

• opts FactoryOptions (optional, default {})

Returns Promise<Daemon>

createTestsInterface

src/index.js:97-121

Create a interface for tests setup

Parameters

• createOptions FactoryOptions (optional, default {})

Returns TestsInterface

createServer

src/index.js:132-137

Create a Endpoint Server

Parameters

• options (Object | number) Configuration options or just the port.
  • options.port number Port to start the server on.

Returns Server

TestsInterfaceCreateNode

src/index.js:139-145

Type: Function

Parameters

• options FactoryOptions

Returns Promise<Daemon> Returns a IPFSd-ctl Daemon

TestsInterfaceSetup

src/index.js:139-145

Type: Function

Parameters

• options FactoryOptions

Returns Promise<IpfsClient> Returns an IPFS core API

TestsInterfaceTeardown

src/index.js:139-145

Type: Function

Returns Promise<void>

TestsInterface

src/index.js:139-145

Type: object

Properties

• node TestsInterfaceCreateNode Create a single unmanaged IPFSd-ctl Daemon
• setup TestsInterfaceSetup Setup a managed node and returns an IPFS Core API
• teardown TestsInterfaceTeardown Stop all managed nodes

IpfsOptions

src/index.js:139-145

Same as https://github.com/ipfs/js-ipfs/blob/master/README.md#ipfs-constructor

Type: Object

Properties

• repo (string | Object)? The file path at which to store the IPFS node’s data. Alternatively, you can set up a customized storage system by providing an ipfs.Repo instance.
• init (boolean | Object)? Initialize the repo when creating the IPFS node. Instead of a boolean, you may provide an object with custom initialization options. https://github.com/ipfs/js-ipfs/blob/master/README.md#optionsinit
• start boolean? If false, do not automatically start the IPFS node. Instead, you’ll need to manually call node.start() yourself.
• pass string? A passphrase to encrypt/decrypt your keys.
• silent boolean? Prevents all logging output from the IPFS node.
• relay object? Configure circuit relay. https://github.com/ipfs/js-ipfs/blob/master/README.md#optionsrelay Default: { enabled: true, hop: { enabled: false, active: false } }
• preload object? Configure remote preload nodes. The remote will preload content added on this node, and also attempt to preload objects requested by this node. https://github.com/ipfs/js-ipfs/blob/master/README.md#optionspreload Default: { enabled: true, addresses: [...]
• EXPERIMENTAL object? Enable and configure experimental features. https://github.com/ipfs/js-ipfs/blob/master/README.md#optionsexperimental Default: { ipnsPubsub: false, sharding: false }
• config object? Modify the default IPFS node config. This object will be merged with the default config; it will not replace it. The default config is documented in the js-ipfs config file docs. https://github.com/ipfs/js-ipfs/blob/master/README.md#optionsconfig
• ipld object? Modify the default IPLD config. This object will be merged with the default config; it will not replace it. Check IPLD docs for more information on the available options. https://github.com/ipfs/js-ipfs/blob/master/README.md#optionsipld
• libp2p (object | function)? The libp2p option allows you to build your libp2p node by configuration, or via a bundle function. https://github.com/ipfs/js-ipfs/blob/master/README.md#optionslibp2p
• connectionManager object? Configure the libp2p connection manager. https://github.com/ipfs/js-ipfs/blob/master/README.md#optionsconnectionmanager
• offline boolean? Run the node offline.

FactoryOptions

src/index.js:139-145

Type: Object

Properties

• remote boolean? Use remote endpoint to spawn the nodes. Defaults to true when not in node.
• port number? Remote endpoint port. (Defaults to 43134)
• host string? Remote endpoint host. (Defaults to localhost)
• secure string? Remote endpoint uses http or https. (Defaults to false)
• defaultAddrs Boolean? Use the daemon default Swarm addrs.
• disposable Boolean? A new repo is created and initialized for each invocation, as well as cleaned up automatically once the process exits.
• type string? The daemon type, see below the options:- go - spawn go-ipfs daemon
  • js - spawn js-ipfs daemon
  • proc - spawn in-process js-ipfs instance
• ipfsHttp Object? Setup IPFS HTTP client to be used by ctl.
  • ipfsHttp.ref Object? Reference to a IPFS HTTP Client object. (defaults to the local require(ipfs-http-client))
  • ipfsHttp.path string? Path to a IPFS HTTP Client to be required. (defaults to the local require.resolve('ipfs-http-client'))
• ipfsApi Object? Setup IPFS API to be used by ctl.
  • ipfsApi.ref Object? Reference to a IPFS API object. (defaults to the local require(ipfs))
  • ipfsApi.path string? Path to a IPFS API implementation to be required. (defaults to the local require.resolve('ipfs'))
• ipfsBin String? Path to a IPFS exectutable . (defaults to the local 'js-ipfs/src/bin/cli.js')
• env Object? Additional environment variables, passed to executing shell. Only applies for Daemon controllers.
• ipfsOptions IpfsOptions? Options for the IPFS instance
• args Array? Custom cli args.

[hugomrdias]

new iteration in html using typedoc and autogenerated type defs all from vanilla js with jsdoc
https://hugomrdias.keybase.pub/ipfsd-ctl-docs/

[NatoBoram]

Wouldn't it be just simpler to migrate everything to TypeScript? Since it's literally just JavaScript with types, you can convert the whole project without changing a thing at first and just add actual types gradually.

[bluelovers]

where are the typescript file at? i didn't see it in this repo

[SgtPooki]

js-ipfs is being deprecated in favor of Helia. You can learn more about this deprecation and read the migration guide.

Please feel to reopen with any comments by 2023-06-02. We will do a final pass on reopened issues afterwards (see #4336).

This should be fixed in Helia since it's written in typescript. I believe libp2p is in the process of being updated to typescript as well.