[docs+comments] fixes and updates