Add additional timer::Error docs. (#311)

Closes #302

tokio-timer/src/error.rs

@@ -4,6 +4,24 @@ use std::error;
 use std::fmt;
 
 /// Errors encountered by the timer implementation.
+///
+/// Currently, there are two different errors that can occur:
+///
+/// * `shutdown` occurs when a timer operation is attempted, but the timer
+///   instance has been dropped. In this case, the operation will never be able
+///   to complete and the `shutdown` error is returned. This is a permanent
+///   error, i.e., once this error is observed, timer operations will never
+///   succeed in the future.
+///
+/// * `at_capacity` occurs when a timer operation is attempted, but the timer
+///   instance is currently handling its maximum number of outstanding delays.
+///   In this case, the operation is not able to be performed at the current
+///   moment, and `at_capacity` is returned. This is a transient error, i.e., at
+///   some point in the future, if the operation is attempted again, it might
+///   succeed. Callers that observe this error should attempt to [shed load]. One
+///   way to do this would be dropping the future that issued the timer operation.
+///
+/// [shed load]: https://en.wikipedia.org/wiki/Load_Shedding
 #[derive(Debug)]
 pub struct Error(Kind);