As shared by @raul in the Kyokan report (original thread can be seen here), some of the findings for adopting
libp2p reported by various developers were “API Inconsistencies” and “Lack of Documentation” (see “ When Implemented And Understood libp2p Has Few Concrete Issues” finding). To showcase the former, I went through the “Getting Started” demo of version
0.27.x and was faced with the following error:
TypeError: Class constructor Mplex cannot be invoked without 'new' at Object.<anonymous> (/Users/hopr/Projects/libp2p/demo-js-libp2p/index.js:6:1)
It took me sometime to realise the documentation was a bit outdated. After a few changes and using other examples, I managed to put the
libp2p-in-the-browser example online (see https://glitch.com/~libp2p-browser-demo), originally put together by @jacobheun.
Now, for the HackFS hackathon, it seems that the most up-to-date (i.e.
0.28.x documentation) lives in the
js-libp2p-examples, with a very good walkthrough and introduction by Jacob. It seems that there isn’t a centralised place where all the documentation for
libp2p with dynamic versions exists, which seems to match the notes from the Kyokan report.
Might I suggest we pool some efforts to put together such documentation? On a first glance this would meant something along these lines:
- Look up for all references from a given implementation (e.g.
js-libp2p) and point them to a single directory/repository (e.g.
- Remove all existent and/or outdated references for specific versions that might no longer be supported and focus on a specific baseline (e.g.
0.28.x). I’m aware
libp2pis yet to be stable and the API is expected to change, but would be good to have a base version we can point entry level engineers to.
- Setup a documentation engine able to generate version specific APIs and render those under a
libp2papproved domain. The API is already in GitHub so it would be a matter of render those in something versionable (e.g. ReadTheDocs)
- Review existing examples, ensure they work, freeze packages, and deploy live URLs users can use to see them working.
As a final note, as part of the KERNEL program, we are looking to actually build this documentation, based on the work already done by @shresthagrawal who put together this tutorial, code source available here. Let us know what would be the best way to collaborate together and/or whether
libp2p and/or associated entities (e.g. Filecoin) have any particular plans in this direction. We would love to work together!