add examples and some clarifications
update changes