Bug 253377

phpDocumentor from which php doc blocks arrived has support for markdown syntax:

http://www.phpdoc.org/docs/latest/references/phpdoc/basic-syntax.html

Here is a quick look at PhpStorm, which has this this feature:

http://blog.jetbrains.com/phpstorm/2014/04/phpstorm-8-markdown-support-in-phpdoc-blocks/

This allows writing rich doc block without embedding html in comments which is *both* human and computer readable.

Example rich text (html) comment:

/**
 * Annotation for embedded document in mongo
 * <code>defaultClassName</code> will be used for getting empty properties,
 * but any type of embedded document can be stored within this field
 * Examples:
 * <ul>
 * 		<li><code>Embedded(Company\Product\EmbeddedClassName)</code>: Embed with namespaced class literal</li>
 * 		<li><code>Embedded(EmbeddedClassName)</code>: Embed with default class</li>
 * </ul>
 */

The same example using markdown syntax:

/**
 * Annotation for embedded document in mongo
 * `defaultClassName` will be used for getting empty properties,
 * but any type of embedded document can be stored within this field
 * Examples:
 * * `Embedded(Company\Product\EmbeddedClassName)`: Embed with namespaced class literal
 * * `Embedded(EmbeddedClassName)`: Embed with default class
 */