(PE-2291) add docstrings and precondition in core

I also made a pass through the core ns, but I didn't find any functions that I thought should be moved elsewhere.