more fixes and doc remarks