adding unit test and documentation for #1983