adding explanations, php docs etc