doc - restored accidentaly deleted comment, added comments for new methods