some docs, refractorings, refinements