Test and fully document the review_in parameter

[AntonOfTheWoods]

anki has a choice between a couple of spaced repetition algorithms, see: https://faqs.ankiweb.net/what-spaced-repetition-algorithm.html and https://anki.tenderapp.com/kb/anki-ecosystem/the-anki-21-scheduler.

These are clearly both very defective when you have significant extra information about the items that the learner is memorising. As an example, let's say a learner has a list of vocabulary items they are learning in a foreign language. They have learnt the word "chunking", and the next repetition is programmed for 7 days time. Let's then assume that the learner has read the word "chunking" in context 50 times in the intervening period, hasn't looked it up on any of those occasions, and now clearly has no utility in having it repeated in Anki. While the learner will obviously not spend a great deal of time saying the item is "easy", it may be more efficient to increase the amount of time before the next review. Let's further suppose that the learner has only seen the word 3x, and has looked it up on every occasion. It is likely useful not only to show the word but possibly to show it earlier than predicted and possibly more often. The algorithm is based on information it gets from the tool, and if significant amounts of extra information about learner's knowledge of the item is available, then that information can be used to tweak the algorithm. It is also a little irrelevant the effect this has on memorisation if not being able to tweak means the learner uses the tool less - the overall benefit will be degraded if the learner stops using the tool because it is frustrating.

There are also cases (for example for language learning) where it is useful to have the entire set of vocabulary (so "all words of the language"). If a learner comes across a word then he should be able to indicate to Anki that he knows the word, so he shouldn't get it showed to him in the normal way - it should be considered "known" and so some multiplier already applied.

While the system will relatively quickly adapt to most of these cases, when the number of items goes into the thousands (so when learning the vocab of any language), having very sophisticated over the showing of cards enables the system to carefully manage the cognitive load placed on the learner. It also significantly enriches what can be done with the database - it means that hundreds/thousands of words can be considered as 'known' yet still have that knowledge confirmed at a later date through the algorithm.

The review_in parameter is an attempt to control this on the API note creation/modification methods. It defaults to the standard behaviour (i.e., an added note is considered as new and cards are programmed as any new cards would be). As this functionality is fully non-standard, it needs to be properly tested and the consequences fully understood.