doc update thanks to @dkuppitz and retain() addition.