documentation rewrite for clarity
merge