tidied up API docs, fixed some underlying DB code