In the PEAR standards there is no reference to HTML, if its allowed or not.
http://pear.php.net/manual/en/standards.sample.php
But I see some people use HTML tags like <kbd> and stuff..
So is HTML allowed?
Will it break some doc parsers?
See http://en.wikipedia.org/wiki/PHPDoc#DocBlock_Description_Details
HTML is supported in the Long Description:
The Long Description continues for as many lines as desired and may contain HTML markup for display formatting.
There is a specific list of tags that PHPDoc supports:
Here is a list of tags supported by phpDocumentor:
<b>— emphasize/bold text<code>— Use this to surround php code, some converters will highlight it<br>— hard line break, may be ignored by some converters<i>— italicize/mark as important<kbd>— denote keyboard input/screen display<li>— list item<ol>— ordered list<p>— If used to enclose all paragraphs, otherwise it will be considered text<pre>— Preserve line breaks and spacing, and assume all tags are text (like XML’s CDATA)<samp>— denote sample or examples (non-php)<ul>— unordered list<var>— denote a variable name
Also of note, it looks like a blank line between paragraphs is interpreted as a paragraph break even without <p> tags.
1
According to this other page they follow the phpDoc standard. You should follow that standard strictly, although some common extensions can sometimes be assumed. For publicly available code (on other projects) I do not put HTML into my phpDoc compatible comments.