improved documentation of efficiency function