validation: added lot of comments and internal documentation