more code formatting and indenting in the higher level docs to make them more readable