add some documentation for updating objects