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=