Add documentation for listing API

Add parameter to define for the sorting criteria of the returned blobs. @xla 
The logic in this function is still hard to follow and to understand and needs commenting with thorough reasoning.