Update conventions around docblocks.
complete doc block docs.
simplify code blocks
Merge pull request #1260 from dereuromark/master-conventions-docblocks

Master conventions docblocks