Although you are free to use HTML in doc comments, it would be wise to do so sparingly. Future versions of knitdoc may support multiple output formats (e.g., LATEX) in addition to HTML.