a bit of reorganization; testing input conditions
adding some documentation