This has come up on slack once or twice, and I've found myself wanting it a number of times. Something like this would be very useful to help document types:

/**
 * @return array<
 *     array-key, --id (TODO change to int)--
 *     string, --name--
 * >
 */

A couple things to note about syntax:

• We should make sure that whatever syntax we use allows every character in the comment, we shouldn't disallow comments like TODO change to iterable<int, string> for instance (eg if the syntax for comments was everything after the first space and before the next comma this would fail)
• Comments should ideally be allowed in single line types, with multiple comments in a single line

I think using --[comment]-- would work ok, but I haven't thought too much about it and I'm very open to alternatives. One plus about using hyphens is that you can't use them in class names, and internal types never use double hyphens, so it should always remain unambiguous.