Define interface

This adds the definition of the public interface. Comments welcome!

@neithernut 
You mean I should mention the error codes in the `@return` statement instead of the `@warning` statement?