Normalize comment blocks

Whilst trying to get people writing yuidoc with our js, they've pointed out that examples are inconsistent.

This attempts to clarify the docblock syntax a little more.