improve the docs to be more godoc compliant