Can’t find docs, examples, source nor tests for .cat()

[haadcode]

Trying to use .cat() and hit some problems. Came over here to find API docs and usage example. However, I can't find any of them :/ The docs are... non-existent? The tests are in some other repo (and not following the general convention of command-per-file in test/ directory).

We need to pull all this together so that it's easy for anyone to come look for help: give them links to appropriate places right when they come in (README), make sure same conventions are followed in the repos for tests so that they're all in one place, make sure each feature that is fully supported by js-ipfs and js-ipfs-api is documented.

[haadcode]

Reported this due to #323

[daviddias]

js-ipfs-api is defined by https://github.com/ipfs/interface-ipfs-core. We need to make this more visible though

[daviddias]

@haadcode see now:

• https://github.com/ipfs/js-ipfs-api#api
• and:

On:

The tests are in some other repo (and not following the general convention of command-per-file in test/ directory).

They have been organized by API - https://github.com/ipfs/interface-ipfs-core/tree/master/src

[daviddias]

Would agree that it is improved now? Any suggestions to make it better?

[haadcode]

It's better.

js-ipfs-api follows the spec defined by interface-ipfs-core, which concerns the interface to expect from IPFS implementations. This interface is a currently active endeavor - expect it to be complete in the next few weeks (August 2016). You can use it today to consult the methods available.

How about just a direct link to the API docs? "API documenationtion here". (update that link to actually contain the API docs, not only in the ToC).

Or:
"See the API documentation in interface-ipfs-core for the full description."

The tests are in some other repo (and not following the general convention of command-per-file in test/ directory).
They have been organized by API - https://github.com/ipfs/interface-ipfs-core/tree/master/src

The confusing part here is that the tests are in src/ and not in test/. It took me a while to look into that directory, it's not an intuitive place. Is it possible to put the tests in test/ like every JS project?

[daviddias]

"See the API documentation in interface-ipfs-core for the full description."

This would not be true, since js-ipfs-api has a constructor specific API (passing the url of the http-api), and there are extra functions (.util.)

Answered about src vs test on ipfs-inactive/interface-js-ipfs-core#65 (comment)

[haadcode]

This would not be true, since js-ipfs-api has a constructor specific API (passing the url of the http-api), and there are extra functions (.util.)

What's there now is not clear is what I'm saying.

What's the API? What are the functions I can use? Those are the questions that part in the README should answer.

[SCBuergel]

Would agree that it is improved now? Any suggestions to make it better?

@diasdavid I'm just getting back after a year or so to IPFS and find this JS API pretty much not usable because I cannot find a simple example of ipfs add SOMETHING and ipfs cat HASH with output to local variable in Node.js as complete walk-through. I assume thats the first and most minimalistic starting point. I am actually browsing the issues to find out how ipfs.add or ipfs.cat can really be used (pipe to stdout is not such a typically useful example). I would expect such examples and at least a summarizing description of all available functions (or at least a list) in README.

[daviddias]

@SCBuergel the feedback is really appreciated, in fact, that is something we want to focus more time in Q4, as the ROADMAP suggests.

Nevertheless, you should be able to find an example in this repo, here, and the API documentation for files here -- https://github.com/ipfs/interface-ipfs-core/tree/master/API/files --

[SCBuergel]

In fairness I'm a very lazy and not very well-versed JS developer. Hence I did not come across streams before - and in my defense it is not mentioned in the readme that you are actually working with native JS streams. Since I guess I am not alone I'd suggest:

• mention that you work either with files (that work as indicated in the example) or streams (with link)
• your default example a-la

var hash = 'QmX7epzCn2jD8nPUDiehmZDQs69HxKYcmMGjd3rmnjd2Ht';
ipfs.cat(hash, function (err, res) {
    if (err || !res) {
      return console.error('ipfs cat error', err, res)
    }
    if (res.readable) {
      console.error('unhandled: cat result is a pipe')
    } else {
      console.log('hash: ' + hash);
      console.log('res: ' + res);
    }
})

just printed me that monstrous stream object which contained almost the entire Encyclopedia Galactica but not the actual data behind the hash. I eventually found the obvious on and was massively happy when I used:

    res.on('data', (chunk) => {
      console.log(`Received ${chunk.length} bytes of data: ` + chunk);
    });

[daviddias]

We've improved documentation by providing:

• examples https://github.com/ipfs/js-ipfs-api/tree/master/examples
• enhanced documentation and referencing to the interface in the readme https://github.com/ipfs/js-ipfs-api#api

@SCBuergel would you like to contribute to the documentation effort?