Inline Example Loses Opening Curly Brace

[donatj]

We have inline examples in a number of our class level doc blocks

The Reflector however is losing our opening curly brace in cases where there is no space ala {}

<?php

/**
 * Description
 *
 * <code>
 * function Foo( Bar $baz ) {}
 * </code>
 *
 */
class FooBaz {
}

Gives us

<code>
function Foo( Bar $baz ) }
</code>

when calling

 $classBlock = $class->getDocBlock()
echo (string)$classBlock->getDescription();

[jaapio]

docblocks are using an escape syntax to prevent issues in some situations. This is release to phpDocumentor/ReflectionDocBlock#276

The escape syntax is {} for a } in the final result. So in your case the docblock would be like this:

<?php

/**
 * Description
 *
 * <code>
 * function Foo( Bar $baz ) {{}
 * </code>
 *
 */
class FooBaz {
}

I understand that this syntax might look odd to you, but given the time this exists in phpDocument since version 1 (about 20 years) we cannot simply change this syntax.

Please follow that issue to see how we can fix this.

[donatj]

@jaapio What kind of things would one be escaping in a doc comment?

Would it be reasonable to disable said escape logic in between code blocks?

[mvriel]

The escaping mechanisms are in place to make sure inline tags won't go wrong (i.e. {@see this thing}) or are inadvertently closed / opened.

Introducing the detection of code blocks provides challenges which are difficult to overcome (i.e. what is a code block? <code></code>, single backticks, fenced backticks, and more; it would also mean that the parsing of DocBlocks becomes irregular and can no longer be done through the use of a, performant, regular expression. phpDocumentor's current speediness is, among other things, gained because we have been able to interpret them regularly and thus use a regular expression to do the initial pass of parsing.

Another caveat is that this method of escaping has been present since the first version, and we need to double or triple check this won't be a BC break and thus cripple documentation of existing projects.