fix doc issues and other code improvements