finish clarifying comments and doc strings