Incorparate feedback and add docs, see #2824