updated docs and tests, supported 3rd arg for value comparison fn
some corrections in docs