some documentation and code rearrangement