clamping + refactoring + docs