documented misc functions