fix #4435

also update doc on dim-reducing functions
plus tests