adding some yard annotations
Improving YARD info and markup throughout