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

[dignifiedquire]

Additional todos for (not needed for initial release though)

• Add @enum support to documentation.js
• Improve @memberof and @namespace handling for documentation.js
• Figure out a way to display and handle nested definitions in documentation.js + clean-documentation-theme

[daviddias]

@dignifiedquire this is shaping to be awesome! ❤️

I believe to make this a perfect landing, we just need to make sure that a) feedback is requested, b) feedback is collected.

Let's focus on getting js-ipfs and js-ipfs-api done first as those will be the most used doc pages.

[RichardLitt]

compile both a markdown version and a html version of the docs (markdown should be available in the README

I would very much like this. I'm not too happy with the API section just being a link to somewhere off-site; that means that the documentation is not close to the code. @dignifiedquire Can I help with this? Is there a ticket tracking this, elsewhere?

[dignifiedquire]

that means that the documentation is not close to the code

the documentation is right in the code, so it's even closer now :P

[daviddias]

@dignifiedquire I believe that is not a valid answer. Can you provide @RichardLitt with:

• How to use jsdoc to generate markdown docs
• Any thoughts you might have to make that a simple thing?

[dignifiedquire]

I'm sorry I just don't agree with the notion of stuffing the readme full of api documentation if we don't have to. Especially for projects where the documentation is more than just a couple of methods. Putting it in a separate markdown file which is not tracked in git and published to npm I think makes sense though.

• Documentation on how to generate markdown docs using documentations.js can be found here: https://github.com/documentationjs/documentation/tree/master/docs
• The gulp task we use is this: https://github.com/documentationjs/gulp-documentation
• The changes would need to be made to aegir
  • https://github.com/dignifiedquire/aegir/blob/master/tasks/docs/build.js
  • Some configuration needs to be added to allow enabling the markdown docs generation.

[RichardLitt]

I'm sorry I just don't agree with the notion of stuffing the readme full of api documentation if we don't have to.

Fair.

Putting it in a separate markdown file which is not tracked in git and published to npm I think makes sense though.

Why no git track?

[dignifiedquire]

Why no git track?

Because it's auto generated and the risk of things getting out of sync on a per commit basis is very high.

[jefft0]

For awesome documentation, each example link should be pinned somewhere so that the reader can try the example. E.g. the example for "This is some data" on the examples page doesn't resolve:

https://ipfs.io/ipfs/QmNZiPk974vDsPmQii3YbrMKfi12KTSNM7XMiYyiea4VYZ/example#/ipfs/QmRFTtbyEp3UaT67ByYW299Suw7HKKnWK6NJMdNFzDjYdX/data/readme.md

Also, the links for the example web site on this page don't work:

https://ipfs.io/ipfs/QmNZiPk974vDsPmQii3YbrMKfi12KTSNM7XMiYyiea4VYZ/example#/ipfs/QmRFTtbyEp3UaT67ByYW299Suw7HKKnWK6NJMdNFzDjYdX/websites/README.md

[daviddias]

Moved the entire tracking of this awesome endeavour to its own PR - #651