added required flag, changed documentation examples to use it