docs: clarify module definition

and minor changes while i'm here