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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Closed

rhertogh wants to merge 2 commits into phpstan:1.22.x from rhertogh:support_one_line_comments

Closed

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

rhertogh wants to merge 2 commits into phpstan:1.22.x from rhertogh:support_one_line_comments

Conversation

rhertogh

Copy link

@rhertogh rhertogh commented Jul 15, 2023

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

rhertogh added 2 commits

July 16, 2023 00:51

@rhertogh


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

e80305e

@rhertogh


 Fixed coding standards and linting for 'support "one-line" comments' ...

5b055b1

...changes

@ondrejmirtes

Copy link

Member

ondrejmirtes commented Jul 16, 2023

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

The comment needs to be available for each type node in the node attributes.
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

Copy link

Author

rhertogh commented Jul 16, 2023

@ondrejmirtes

The comment needs to be available for each type node in the node attributes.

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

Copy link

Member

ondrejmirtes commented Jul 17, 2023

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

Copy link

Contributor

shmax commented Aug 28, 2023

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

@shmax

Copy link

Contributor

shmax commented Sep 1, 2023

@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...