Describe when and why to use init: false

[Mr0grog]

This adds some description to the "advanced options" documentation for the IPFS constructor detailing that init: false should really be used if a repo has already been initialized by IPFS and that simply calling repoInstance.init() doesn't init a repo with everything IPFS needs.

This partially handles #1245, but other parts of the experience (e.g. #1262) could also be improved.

Does this help clarify things? Or is it too confusing?

Is there anywhere else these options are documented that I need to update? (I couldn’t find anywhere, but I wouldn’t be surprised if I missed something.)

[dryajov]

This looks good - thanks @Mr0grog!

[dryajov]

Perhaps @diasdavid has more (historical) insight into that - but it might be worth adding that, even though IPFS takes a repo instance its not intended (IMHO) to be initialized outside of IPFS at all.

[daviddias]

I'm not sure I don't understand what this comment is trying to prevent the user to do. Either a user knows what they are doing and they know supposed pitfall or they don't and the terms here don't give them any other help.

[Mr0grog]

OK. We clearly have users who don’t know what this is for. As noted in the summary, this is trying to prevent a user from having the kind of misunderstanding they had in #1245.

What language would you suggest better clarifies when to and not to use init: false? What should I say here that helps someone like that know they shouldn’t just:

const repo1 = new IPFSRepo('/tmp/ipfs-repo1');
repo1.init({}, (err) => {
  if (err) { console.log(err); return; }

  const node1 = new IPFS({
    repo: repo1,
    init: false,
    start: true
  });

  node1.on('start', () => {
    console.log('IPFS node 1 started.');
  });
})

Something like:

Use this if the repo has previously been initialized by passing it to new IPFS(). You should not attempt to call init() yourself on an IPFSRepo instance and then set init: false here.

?

Clearly this could go into a lot more detail, but because this is all inline in a code sample, there’s not a whole lot of room. There’s no other place to document this stuff, right?

[mitra42]

I think part of the confusion with repo is how you right code so that it works both the first time its called, and following times. init confused me a lot when I first saw it. Do I
a) set init=true - in which case I would assume it will clear the repo every time, losing all saved data or
b) set init=false in which case it will fail the first time.

I think most distributed IPFS based apps are going to want to default to "initialize a new repo if it doesn't exist, or if its incompatible (because IPFS has changed version and broken old repo's) and otherwise leave it alone". I still have no clue wither that is to set it to false, true or leave it missing (which is what we currently do. )

Some comments here about when to set it to true, when to false, and when to omit it would be useful.

[daviddias]

@Mr0grog what about this? :)

[daviddias]

I'll go ahead an merge this as it improves on existing docs. If a new review is needed, feel welcome to submit another PR :)