Js-ipfs: RFC: generated API docs from typescript declarations

[alanshaw]

I had an idea in https://github.com/ipfs/js-ipfs/pull/651#issuecomment-542132633 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 https://github.com/ipfs/interface-js-ipfs-core/pull/541#issuecomment-543338311 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 https://github.com/TypeStrong/typedoc/issues/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: https://github.com/alanshaw/abortable-iterator/pull/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