Awesome Endeavour: API Documentation

[dignifiedquire]

Ref #615
Preview: http://ipfs.github.io/js-ipfs/

---

---

Awesome API Documentation

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

[daviddias]

Moved #615 tracking to here ^^

[daviddias]

It's currently very painful that PR's to add docs have been removing API docs entirely from the README without ensuring that docs generated are available 100% of the time. We've received multiple bug reports of users simply not being able to find docs.

[daviddias]

Let's close this PR as wontfix with this approach. 👍 ?

[alanshaw]

👍... I think we should revisit this in the future, but agreed, not right now and this PR is so old that it would be super painful to merge anyway.

[daviddias]

Now with the #1670 coming to an end, the good progress on merging non-swappable code pieces #2222 and the previous notes on sustainable modules ipfs/notes#273, I believe it might be the right time to reconsider http://documentation.js.org

@alanshaw @achingbrain what's your take? @ipfs/docs what's your advice?

[cwaring]

👋 I haven't solved the best approach to integrate generated documentation yet however we will want to optimise the output so that it can be nicely consumed by VuePress(the platform I'm building the POC with over the next month). Essentially markdown with custom front matter.

At this stage I feel like we should have a docs app for each language implementation in order to have fine grain control over versioning and internationalisation, these are things we should discuss once I'm further down the road with the prototype.

[alanshaw]

I had this idea that we'd 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 that which would give us incentive to keep them up to date and make js-ipfs more friendly to our community of typescript users!

What do you think?

[cwaring]

@alanshaw that sounds like a great idea with a double benefit. Would you use tsdoc for this? There is a markdown plugin that might help us out too.