factor out duplicate code, doc, lint fixes,