如何在docblock评论中显示代码示例？

Question

I've written a docblock comment for a class property in PHP using netbeans 7.3. The property being commented is an associative array, so I'd like to comment on each key. Here's the code:

/**
 * The expression being built.
 * 
 * This will be pushed to the {@see $_parts} array when complete.
 * <code>
 * array(
 *      'schema',       # The qualified schema name
 *      'table',        # The qualified table name
 *      'column',       # The qualified column name
 *      'alias',        # A simple name for schema.table.column
 *      'expr'          # A nested (in parenthesis) Expression object.
 *      'raw'           # Used for unrecognized expressions.
 *      'operator',     # The operator comparing column and value
 *      'value',        # The value(s) to compare column against
 *      'eval'          # A callable method to do the compare.
 *      'query'         # A sub Query (or Transaction) object.
 * )
 * </code>
 * 
 * @var mixed[]
 */
protected $_unit = array();

I was hoping the <code> block would preserve the line formatting. The problem is, new line characters in the comment are being ignored and all multi spaces are condensed to a single space, when using the "auto popup documentation window". This makes it very hard to read.

Is there another way to preserve the format, or at least make it readable?

Answer 1

Try it with <pre> tags around the <code> tags. Else just use <br>.

From phpDocumentor:

<code> -- Use this to surround php code, some converters will highlight it
<pre> -- Preserve line breaks and spacing, and assume all tags are text (like XML's CDATA)
<br> -- hard line break, may be ignored by some converters

Example:

/**
 * The expression being built.
 *
 * This will be pushed to the {@see $_parts} array when complete.
 * <pre>
 * <code>
 * array(
 *      'schema',       # The qualified schema name
 *      'table',        # The qualified table name
 *      'column',       # The qualified column name
 *      'alias',        # A simple name for schema.table.column
 *      'expr'          # A nested (in parenthesis) Expression object.
 *      'raw'           # Used for unrecognized expressions.
 *      'operator',     # The operator comparing column and value
 *      'value',        # The value(s) to compare column against
 *      'eval'          # A callable method to do the compare.
 *      'query'         # A sub Query (or Transaction) object.
 * )
 * </code>
 * </pre>
 *
 * @var mixed[]
 */