feat: more readable phpdoc escaping #11208
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This was referenced Dec 8, 2022
haberman
reviewed
Feb 2, 2023
haberman
added
the
🅰️ safe for tests
github-actions
bot
removed
the
🅰️ safe for tests
|
@haberman is there anything preventing this from being merged? |
|
@bshaffer it looks like a bunch of the tests are failing. Rebasing and re-pushing should help. |
1 task
bshaffer
force-pushed
the
more-readable-phpdoc-escaping
branch
from
542c513
to
a75f974
Compare
|
@haberman sorry for the delay here. Done! |
|
We triage inactive PRs and issues in order to make it easier to find active work. If this PR should remain active, please add a comment. This PR is labeled |
github-actions
bot
added
the
inactive
|
This is an important feature, please don't just automatically close this |
github-actions
bot
removed
the
inactive
copybara-service bot
pushed a commit
that referenced
this pull request
Jan 31, 2024
The PHPDoc escaping in PHP is aggressive in that it escapes some character sequences that don't need to be escaped (`/*`), and it uses HTML entities to escape others (`*/` and `@`) instead of the recommended PHPDoc escape sequences. For Example, in [`Google\Api\RoutingParameter`](https://github.com/googleapis/common-protos-php/blob/main/src/Api/RoutingParameter.php#L42): ``` * path_template: "projects/*/{table_location=instances/*}/tables/*" ``` Should be escaped as: ``` * path_template: "projects/{@*}{table_location=instances/*}/tables/*" ``` according to [the PHPDoc guide](https://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.desc): - For `@`: "if you need an actual "@" in your DocBlock's description parts, you should be careful to either ensure it is not the first character on a line, or else escape it ("\\@") to avoid it being interpreted as a PhpDocumentor tag marker." - For `*/`: " If you need to use the closing comment "\*/" in a DocBlock, use the special escape sequence "{@*}." Closes #11208 COPYBARA_INTEGRATE_REVIEW=#11208 from bshaffer:more-readable-phpdoc-escaping a75f974 FUTURE_COPYBARA_INTEGRATE_REVIEW=#11208 from bshaffer:more-readable-phpdoc-escaping a75f974 PiperOrigin-RevId: 602870442
deannagarcia
pushed a commit
to deannagarcia/protobuf
that referenced
this pull request
Jun 20, 2024
The PHPDoc escaping in PHP is aggressive in that it escapes some character sequences that don't need to be escaped (`/*`), and it uses HTML entities to escape others (`*/` and `@`) instead of the recommended PHPDoc escape sequences. For Example, in [`Google\Api\RoutingParameter`](https://github.com/googleapis/common-protos-php/blob/main/src/Api/RoutingParameter.php#L42): ``` * path_template: "projects/&protocolbuffers#42;&protocolbuffers#47;{table_location=instances/&protocolbuffers#42;}/tables/&protocolbuffers#42;" ``` Should be escaped as: ``` * path_template: "projects/{@*}{table_location=instances/*}/tables/*" ``` according to [the PHPDoc guide](https://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.desc): - For `@`: "if you need an actual "@" in your DocBlock's description parts, you should be careful to either ensure it is not the first character on a line, or else escape it ("\\@") to avoid it being interpreted as a PhpDocumentor tag marker." - For `*/`: " If you need to use the closing comment "\*/" in a DocBlock, use the special escape sequence "{@*}." Closes protocolbuffers#11208 COPYBARA_INTEGRATE_REVIEW=protocolbuffers#11208 from bshaffer:more-readable-phpdoc-escaping a75f974 PiperOrigin-RevId: 603091642
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The PHPDoc escaping in PHP is aggressive in that it escapes some character sequences that don't need to be escaped (
/*), and it uses HTML entities to escape others (*/and@) instead of the recommended PHPDoc escape sequences.For Example, in
Google\Api\RoutingParameter:Should be escaped as:
according to the PHPDoc guide:
For
@: "if you need an actual "@" in your DocBlock's description parts, you should be careful to either ensure it is not the first character on a line, or else escape it ("\@") to avoid it being interpreted as a PhpDocumentor tag marker."For
*/: " If you need to use the closing comment "*/" in a DocBlock, use the special escape sequence "{@*}."