Deine Kommentare durchgelesen und beantwortet.
Außerdem noch ein paar Ideen reingeschrieben.
Ein paar Kommentare angepasst, z.B: bei @return true v false
habe ich geändert zu @return boolean und dann geschrieben, wann true raus kommt und wann false.