PIM-3197: add specs to the sorters
PIM-3197: clean phpdoc