clarifications to docs