Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
add comment

2 Answers

up vote 1 down vote accepted

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.