Awesome API Documentation Endeavour

[dignifiedquire]

We want to improve the documentation in the whole project and for that this endeavour exists.
To improve the documentation we settled on using jsdoc style inline comments to describe the APIs and after that using documentation.js to generate beautiful docs.

If you want to help out, please comment on this issue which module you are tackling.

Test Instructions

Currently the integration into aegir is not yet done, so when documenting you can use documentation.js directly to test that everything works fine.

• Update aegir to ^9.2.0
• Add a script to package.json with "docs": "aegir-docs"
• Run npm run docs
• open docs/index.html in your favorite browser

Modules

IPFS

Name	JSDOC	Assignee
js-ipfs-bitswap
js-libp2p-ipfs-browser
js-libp2p-ipfs
js-ipfs-block
js-ipfs-api	ipfs-inactive/js-ipfs-http-client#469
js-ipfs	#651	@dignifiedquire
js-ipfs-unixfs-engine
js-ipfs-block-service
js-fs-pull-blob-store
js-idb-pull-blob-store
js-ipfs-repo
interface-pull-blob-store

IPLD

Name	JSDOC	Assignee
js-cid	multiformats/js-cid#9	@dignifiedquire
js-ipld-dag-cbor
js-ipld-resolver
js-ipld-dag-pb
js-ipld-eth-block

libp2p

Name	JSDOC	Assignee
js-libp2p-spdy
js-libp2p-webrtc-star
js-libp2p-floodsub
js-peer-info	libp2p/js-peer-info#31	@dignifiedquire
js-peer-id	libp2p/js-peer-id#41	@dignifiedquire
js-libp2p-crypto	libp2p/js-libp2p-crypto#48	@dignifiedquire
js-peer-book	libp2p/js-peer-book#14	@dignifiedquire
js-libp2p-secio
js-libp2p-websockets
js-libp2p-identify	libp2p/js-libp2p-identify#22	@dignifiedquire
js-libp2p-tcp	libp2p/js-libp2p-tcp#50	@dignifiedquire

multiformats

Name	JSDOC	Assignee	URL	Shipped
js-multiaddr	multiformats/js-multiaddr#31	@victorbjelkholm	https://multiformats.github.io/js-multiaddr/	✅
js-multibase	multiformats/js-multibase#9	@dignifiedquire	https://multiformats.github.io/js-multibase/	✅
js-multistream-select	multiformats/js-multistream-select#28	@dignifiedquire	https://multiformats.github.io/js-multistream-select/	✅
js-multihashing-async	multiformats/js-multihashing-async#5	@dignifiedquire	https://multiformats.github.io/js-multihashing-async/	✅
js-multicodec	multiformats/js-multicodec#9	@dignifiedquire	https://multiformats.github.io/js-multicodec/	✅
js-multihash	multiformats/js-multihash#23	@dignifiedquire	https://multiformats.github.io/js-multihash/	✅

Other work

• Aegir integration of documentation.js Implement doc generation and upload aegir#77
• Clean documentation theme: https://github.com/dignifiedquire/clean-documentation-theme

[victorb]

Thanks @dignifiedquire! I would love to help out with either js-ipfs-api or js-ipfs! 🤗 Also, I can probably tackle js-multiaddr

[dignifiedquire]

• Published a first version of the new theme on npm: http://npmjs.com/clean-documentation-theme
• Published test version of documentation for peer-id here: http://libp2p.github.io/js-peer-id

[victorb]

@dignifiedquire we should probably add a link to the repository in the top right or something like that in the theme as well

[dignifiedquire]

@dignifiedquire we should probably add a link to the repository in the top right or something like that in the theme as well

Yes, but need to implement that first in documentation.js, ref documentationjs/documentation#612

[dignifiedquire]

@victorbjelkholm I take that back, added it :)

[dignifiedquire]

@victorbjelkholm @diasdavid just created ipfs/aegir#78