updated docblocks of two methods
+ fixed usage of array_shift where it expects a reference to the original array (thus directly pushing the result in, isnt possible)