improved comments and doc formatting