Documentation updates

The API for beat.core is rather complete and well-documented. It would be good to catch up with the rest of the documentation before our next deliverable (by end of April/2015).