clarify documentation markup
Merge pull request #637 from dereuromark/master-doc-markup

clarify documentation markup