I wonder if we shouldn't put this sort of method documentation just above the method definition instead of inside the body of the method in yarddoc style - http://yardoc.org/