[WIP] add more YARD docs

[jbodah]

@tcopeland this PR has a couple shout outs to you. Would you mind explaining what the notated blocks are doing?

This branch depends on #35 for doc links to be correct

Thanks!

[jbodah]

@tcopeland would you mind explaining what's going on here?

[tcopeland]

Hey sorry for the delay in replying @jbodah.

The problem this is trying to solve is illustrated in this sequence of method calls:

x = foo.select {|y| y > 2 }
z = x.first
x.each {|q| puts q }

Normally pippi would flag that code since select is called and then first is called on the result. But in this case, the result is also used as a collection later - that is, we call each on it. So the code can't be simplified down into a single call to detect.

Pippi's logic is more or less to add a Problem, and then remove it if needed. There might be a nicer way to do that... like, adding it as a provisional problem and not actually adding it to the report until we confirm it.