-
Notifications
You must be signed in to change notification settings - Fork 15.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: more readable phpdoc escaping (#11208)
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 PiperOrigin-RevId: 603091642
- Loading branch information
1 parent
f8ea418
commit f929439
Showing
3 changed files
with
47 additions
and
16 deletions.
There are no files selected for viewing
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 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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
syntax = "proto3"; | ||
|
||
package foo; | ||
|
||
message TestSpecialCharacters { | ||
// test special characters (shouldn't escape): ;,/?:&=+$-_.!~*'() | ||
// test open comment (shouldn't escape): /* | ||
// test close comment (should escape): */ | ||
// test at-sign (should escape): @foo | ||
// test forward slash as first character on a newline: | ||
/// | ||
string a = 1; | ||
|
||
/// | ||
// test forward slash as first character on first line | ||
string b = 2; | ||
} |
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