update docstrings, tidy up some ctors
sanitize the generation of 'name' attributes