added required falg, changed documentation examples to use it