some renaming, and a bit more documentation