More scrobbling documentation

doc/scrobbling.md

@@ -1,25 +1,30 @@
 # Scrobbling
 
+## Features
+
+- Easy scrobbling to Last.fm
+- Scrobble multiple tracks at a time
+- Automatic caching for scrobbles in the event of no network connection (if caching is enabled)
+- Database independent design - easy to integrate the scrobble cache with your preferred database
+
 ## Quickstart
 
+```IScrobbler``` provides an interface for scrobbler classes. The ```Inflatable.Lastfm``` package comes with a basic scrobbler that does not support caching; to get caching you can use the SQLiteScrobbler provided in ```Inflatable.Lastfm.SQLite``` package, or you can [integrate your own database](#extensibility).
+
 Create the scrobbler class:
 ```c#
-var auth = new LastAuth(key, secret);
-var scrobbler = new Scrobbler(auth);
-```
+IScrobbler _scrobbler;
 
-Or if using a SQLite database:
-```c#
-var scrobbler = new SQLiteScrobbler(auth, databasePath);
+var auth = new LastAuth(key, secret, httpClient);
+_scrobbler = new Scrobbler(auth, httpClient);
 ```
 
 then
 
 ```c#
-var scrobble = new Scrobble("65daysofstatic", "The Fall of Math", "Hole", DateTimeOffset.UtcNow);
-
-var response = await scrobbler.ScrobbleAsync();
+List<Scrobble> scrobbles;
 
+var response = await _scrobbler.ScrobbleAsync(scrobbles); // scrobbles will be sent in batches of 50
 if (response.Success)
 {
 	// The scrobble was either successfully sent or has been cached to be sent later.
@@ -39,18 +44,61 @@ else
 
 ```
 
+If used in a music app, this code should be used immediately after a track has finished playing.
+
+## Things to know
+
+### Scrobbles are sent in batches of 50
+
+The Last.fm API supports up to 50 scrobbles being sent at a time. This is handled for you when using an IScrobbler class from the SDK.
+
+### There is a limit on how many scrobbles may be sent in each day
+
+There must be at least 30 seconds in between each scrobble. This means you may scrobble at most ```(24 * 60 * 60) / 30 = 2880``` tracks in one day. If this limit is reached then the scrobbles will be cached if it's enabled.
+
+### Scrobbling is opportunistic
+
+As currently implemented, Scrobblers will only scrobble when the ScrobbleAsync() method is called. Any cached scrobbles will be sent then, and only then. As an illustration, this is a scenario involving our friendly test-subject, User:
+
+- User is commuting to their employment at Business Corporation. They are listening to a playlist of track1, track2 and track3.
+- The application is set up to call scrobbler.ScrobbleAsync() when a track is finished playing.
+- User's train enters a tunnel. 
+- When track1 finishes, User has no network connection. If caching is enabled, then the scrobble is cached.
+- User's train exits the tunnel.
+- When track2 finishes, User now has a network connection. The call to scrobbler.ScrobbleAsync() inspects its cache, and ends up sending both track1 and track2.
+- User is content in the presence of accurate statistics.
+- User's train enters another tunnel.
+- Track3 finishes playing, but User has no network connection. The scrobble for track3 is cached for later.
+- Since the User's playlist has ended, they duly unplug their headphones and exit the train.
+
+At this point, track1 and track2 have been scrobbled - but track3 has not! Track3 is in the scrobble cache. It is not until User's commute, back to their residence in Townsville, when they listen to track4. Only when track4 is finished playing will track3 be scrobbled.
+
+Solving this problem requires some sort of background task to empty the cache. You can write your own that calls ```scrobbler.SendCachedScrobblesAsync()```.
+
+### Scrobbles have an age limit
+
+Last.fm do not accept scrobbles which are older than two weeks (UTC). There's no point sending them, so Scrobbles passed to ScrobbleAsync() which are older than two weeks will be silently dropped.
+
+Right now there is no way to know when this happens. At some point this information will be made available in the reponse object. (#issue number tba)
+
 ## Extensibility
 
-```IF.Lastfm.Core.Scrobblers.Scrobbler```, the core implementation of IScrobbler doesn't cache failed requests. 
-
-The ```ScrobblerBase``` class provides the mechanism for caching scrobbles. Classes deriving it may implement scrobble caching using an external database - if the scrobble request fails, then it will be saved to a database to be sent later. Currently, any cached scrobbles can either be sent when ```ScrobbleAsync(Scrobble s)``` is next called, or independently by calling ```SendCachedScrobblesAsync()```.
+The ScrobblerBase class may be extended in your own project to integrate with the database that suits you best. The derived class needs to implement ```GetCachedScrobblesAsync()```, which should return an IEnumerable<Scrobble>, and ```CacheAsync(Scrobble s)``` which should return LastResponseStatus.Cached if successful or throw an exception if not. Exceptions thrown in CacheAsync() will be caught and returned to the user as error codes (see: #5).
 
 ### SQLite
 
-The ```IF.Lastfm.SQLite.SQLiteScrobbler``` class enables scrobble caching using a SQLite database. 
+SQLite is the first supported database for scrobble caching.
 
+```c#
+IScrobbler _scrobbler;
 
-This is in the NuGet package:
+var databasePath = "scrobbles.db"; // if you are already using SQLite, you may be able to use the same database file.
+File.Create(databasePath); // there *must* be a file present at this location before calling ScrobbleAsync().
+
+_scrobbler = new SQLiteScrobbler(auth, databasePath, httpClient);
+```
+
+To use the SQLiteScrobbler, install [Inflatable.Lastfm.SQLite]() from NuGet. This package will be updated according to major versions of sqlite-net-pcl.
 
 ```
 Install-Package Inflatable.Lastfm.SQLite