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.libp2p/js-libp2p-examples
). - 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 awarelibp2p
is 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
libp2p
approved 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!