improving documentation on model methods