added more documentation to the API (still very incomplete)