fix algorithm and document it.