even more documentation and examples

  and an improved in-directory testing function