add yard gem, mark private api and add a couple of examples to docs [skip ci]