add some documentation to common methods