[Documentation] Use of the on= argument for joins

[stephlocke]

The on= argument for data.table has minimal documentation at present, and does not feature in FAQs. It is, of course, a rather hard to search for the term.

I'd like to see the following:

1. A wiki page on all things JOIN in data.table
2. An entry in the FAQ about different join methods
3. More illustrative examples in the documentation about the features and limitations of on=

[stephlocke]

Started on the wiki content. Started at setkey() as it seemed a bit weird to jump to on= without coverage of keys and JOINs first.
https://github.com/Rdatatable/data.table/wiki/Keys

[jangorecki]

R has great infrastructure for keeping docs. I would advocate to put such doc as a part of the package, so in vignettes or new Rd manuals. I'm quite OK on keeping GH related docs (support/contribution/installation/etc.) as GH wiki, but strictly project related stuff within the project content. So I would move fread wiki to vignettes too at some point.
BTW. AFAIK Arun is working on joins vignettes, so probably he handled on argument there.

[stephlocke]

Agreed - vignettes would be fantastic.

@arunsrinivasan, I'm happy to port content over via PR?

[arunsrinivasan]

I think you've not seen f55d35b and a2cb83a ?

Also, recently added Secondary indices and Auto indexing explains the rationale for on= argument along with examples.

The next vignette joins will also focus on on=, but I'm in the process of wrapping up non-equi joins. So most likely, it'll happen after that.

In essence, on your points:

1. Join vignette will be added (and I think it's better than Wiki). Keep track of Vignettes #944.
2. Makes sense. Adding FAQ explaining just the rationale behind on= argument would be great!
3. See links above.

@jangorecki on fread, moving it to vignettes is the plan, yes.

[arunsrinivasan]

Noted point 2 in #944.

[arunsrinivasan]

On keys, there's an entire vignette dedicated to it.. (and will be more with join vignette) why the wiki? Is it addressing something different?