- better inline docs, part #2 and #3