Docs navigation is very confusing

The docs navigation is very confusing. The examples show the Ipfs module, but there's no obvious way to know where the docs for this are. Turns out it's on this page https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs/docs/MODULE.md but there's no obvious link to this page from the front page. MODULE is not a descriptive enough name for someone familiar with the JS ecosystem to know it means the Ipfs constructor.

Now from that MODULE page, I can see that it creates a node instance, but no obvious link to the documentation of this instance. It kind of implies to go to this page https://github.com/ipfs/js-ipfs/tree/master/docs/core-api, which turns out is what a node is, but that was not obvious to me, and I have to click each page to see what's available.

A more reader friendly way to do docs would have every single API on a single page with table of content. Kind of like this https://github.com/puppeteer/puppeteer/blob/v5.2.1/docs/api.md

Also, none of the APIs have events listed. Is there no events available?

[welcome]

Thank you for submitting your first issue to this repository! A maintainer will be here shortly to triage and review.
In the meantime, please double-check that you have provided all the necessary information to make this process easy! Any information that can help save additional round trips is useful! We currently aim to give initial feedback within two business days. If this does not happen, feel free to leave a comment.
Please keep an eye on how this issue will be labeled, as labels give an overview of priorities, assignments and additional actions requested by the maintainers:

• "Priority" labels will show how urgent this is for the team.
• "Status" labels will show if this is ready to be worked on, blocked, or in progress.
• "Need" labels will indicate if additional input or analysis is required.

Finally, remember to use https://discuss.ipfs.io if you just need general support.

[Velua]

As a newcomer, I had no clue what I was doing till finding this issue. So can back this claim.

[achingbrain]

This is useful feedback, thanks. We can certainly take a look at making the docs easier to follow, and having some of it buried under /packages/ipfs and some of it under /docs is a bit confusing so I think certainly bringing everything under /docs is a good start.

Also, none of the APIs have events listed. Is there no events available?

The node returned from IPFS.create() is not an event emitter, nor are instances of the ipfs-http-client, mostly because go-ipfs doesn't present any mechanism for receiving events via the HTTP RPC API so having that be part of the core-api would be difficult without adding real-time events to go-ipfs.

I'd like to see more real-time feedback in js-ipfs though, what events were you expecting?

I'd like to see more real-time feedback in js-ipfs though, what events were you expecting?

I haven't used IPFS much, I just wanted to test it, and try to understand how it works under the hood. For example I wanted to log whenever a peer connects, whenever I send/receive messages to a peer, what this message is, etc. So I wasn't looking for a particular event that wasn't there.

I also wanted to use webRTC specifically to test and not an http provider. I still haven't been able to achieve that yet in the few hours I've tried.

My goal would be to make some browser p2p app that only uses webRTC transport, and also shows statistics about the peers, like how many are connected, how much data sent/received, what country they are from, etc. Not sure if that's possible.

[Gozala]

Current plan is to add jsdoc comments into js-ipfs #3281 repos, finish up changes to aegir ipfs/aegir#568 that would allow us to generate docs from that. And then iterate over improvements to documentation. If anyone is interested in helping moving any of the pieces to get there, help would be appreciated.

I'll post updates here as things progress.