Support "one-line" comments (starting with //)

[rhertogh]

This PR adds support for comments inside type definitions, e.g.:

/** @return array { // Array with comments.
 *     // Comments can be placed on their own line. 
 *     foo: string, // An array key description.
 *     bar: array {, // Another array key description.
 *         'foo//bar': string, // Array key with "//" in it's name.
 *     },
 * }
 */

Fixes #184

[ondrejmirtes]

Hi, thank you, I have a few points that will makes this more complicated.

1. The comment needs to be available for each type node in the node attributes.
2. The comments need to be correctly preserved for the format-preserving printer, meaning it will get a bit more complicated. Fortunately it's heavily inspired by the printer from nikic/PHP-Parser so we have some starting point.

[rhertogh]

@ondrejmirtes

1. The comment needs to be available for each type node in the node attributes.
2. The comments need to be correctly preserved for the format-preserving printer, meaning it will get a bit more complicated. Fortunately it's heavily inspired by the printer from nikic/PHP-Parser so we have some starting point.

Could you point me to the locations where this should be implemented, then I'll give it a shot.

[ondrejmirtes]

Comments need to be added as attributes similarly to how Attribute::START_LINE is added today. See calls to methods called enrichWithAttributes.

As for Printer, see tests in PrinterTest. Comments should be preserved correctly when printing the same PHPDoc again, and correct comment should be removed when for example removing a key from an array shape.

[shmax]

@rhertogh do you have any plans to proceed with this PR? I think it's an important feature... 🙏

[shmax]

@ondrejmirtes

In the event that @rhertogh is MIA, any chance I can prevail upon you to implement this? If you're too busy I can take a crack at it, but I have to confess I couldn't make much sense of the printer tests...

[rhertogh]

@shmax Haven't found the time to continue working on this😅. So if you want to take a swing at it please feel free to do so.

[shmax]

Okay, will do. 👍