Skip to content

Commit 1a8fba1

Browse files
bshafferpurvavasudeo
bshaffer
authored and
purvavasudeo
committed
docs: add enum types to protobuf enum getters and setters (googleapis#8558)
1 parent 973d448 commit 1a8fba1

9 files changed

Lines changed: 94 additions & 20 deletions

‎dev/src/DocFx/Node/MethodNode.php‎

Lines changed: 58 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ class MethodNode
3030
use ParentNodeTrait;
3131
use VisibilityTrait;
3232

33+
private const ENUM_REGEX = '/Generated from protobuf field <code>(\.google\.[\w\.]+)/';
34+
3335
public function __construct(
3436
private SimpleXMLElement $xmlNode,
3537
private string $namespace,
@@ -46,18 +48,26 @@ public function getReturnType(): string
4648

4749
public function getReturnDescription(): string
4850
{
51+
$description = '';
4952
if ($this->xmlNode->docblock) {
5053
foreach ($this->xmlNode->docblock->tag as $tag) {
5154
if ($tag['name'] == 'return') {
5255
if ((string) $tag['description']) {
53-
return (string) $tag['description'];
56+
$description = (string) $tag['description'];
5457
}
5558
break;
5659
}
5760
}
5861
}
5962

60-
return '';
63+
if ($enum = $this->getProtobufEnumGetterType()) {
64+
$enumName = array_reverse(explode('.', $enum))[0];
65+
$description = trim($this->replaceProtoRef(
66+
sprintf('Enum of type [%s][%s]. ', $enumName, $enum)
67+
) . $description);
68+
}
69+
70+
return $description;
6171
}
6272

6373
private function getReturnTypeTag(): string
@@ -120,6 +130,10 @@ public function getParameters(): array
120130
}
121131
}
122132
}
133+
if ($enum = $this->getProtobufEnumSetterType()) {
134+
$enumName = array_reverse(explode('.', $enum))[0];
135+
$description = sprintf('Enum of type [%s][%s]. ', $enumName, $enum) . $description;
136+
}
123137
$parameter = new ParameterNode(
124138
$parameterName,
125139
(string) $parameterNode->type,
@@ -176,4 +190,46 @@ public function getContent(): string
176190

177191
return $content;
178192
}
193+
194+
private function getProtobufEnumSetterType(): ?string
195+
{
196+
if (0 !== strpos($this->getName(), 'set')) {
197+
return null;
198+
}
199+
200+
if (1 !== count($this->xmlNode->argument)) {
201+
return null;
202+
}
203+
204+
if ('int' !== (string) $this->xmlNode->argument[0]->type) {
205+
return null;
206+
}
207+
208+
if (!preg_match(self::ENUM_REGEX, $this->getLongDescription(), $matches)) {
209+
return null;
210+
}
211+
212+
return $matches[1];
213+
}
214+
215+
private function getProtobufEnumGetterType(): ?string
216+
{
217+
if (0 !== strpos($this->getName(), 'get')) {
218+
return null;
219+
}
220+
221+
if (0 !== count($this->xmlNode->argument)) {
222+
return null;
223+
}
224+
225+
if ('int' !== $this->getReturnType()) {
226+
return null;
227+
}
228+
229+
if (!preg_match(self::ENUM_REGEX, $this->getLongDescription(), $matches)) {
230+
return null;
231+
}
232+
233+
return $matches[1];
234+
}
179235
}

‎dev/tests/fixtures/docfx/Vision/V1.BatchOperationMetadata.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ items:
6868
returns:
6969
-
7070
var_type: int
71+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\BatchOperationMetadata\State">State</xref>.'
7172
-
7273
uid: '\Google\Cloud\Vision\V1\BatchOperationMetadata::setState()'
7374
name: setState
@@ -82,7 +83,7 @@ items:
8283
-
8384
id: var
8485
var_type: int
85-
description: ''
86+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\BatchOperationMetadata\State">State</xref>. '
8687
returns:
8788
-
8889
var_type: $this

‎dev/tests/fixtures/docfx/Vision/V1.Block.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,7 @@ items:
234234
returns:
235235
-
236236
var_type: int
237+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Block\BlockType">BlockType</xref>.'
237238
-
238239
uid: '\Google\Cloud\Vision\V1\Block::setBlockType()'
239240
name: setBlockType
@@ -248,7 +249,7 @@ items:
248249
-
249250
id: var
250251
var_type: int
251-
description: ''
252+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Block\BlockType">BlockType</xref>. '
252253
returns:
253254
-
254255
var_type: $this

‎dev/tests/fixtures/docfx/Vision/V1.FaceAnnotation.Landmark.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ items:
5757
returns:
5858
-
5959
var_type: int
60+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\FaceAnnotation\Landmark\Type">Type</xref>.'
6061
-
6162
uid: '\Google\Cloud\Vision\V1\FaceAnnotation\Landmark::setType()'
6263
name: setType
@@ -71,7 +72,7 @@ items:
7172
-
7273
id: var
7374
var_type: int
74-
description: ''
75+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\FaceAnnotation\Landmark\Type">Type</xref>. '
7576
returns:
7677
-
7778
var_type: $this

‎dev/tests/fixtures/docfx/Vision/V1.FaceAnnotation.yml‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -461,6 +461,7 @@ items:
461461
returns:
462462
-
463463
var_type: int
464+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>.'
464465
-
465466
uid: '\Google\Cloud\Vision\V1\FaceAnnotation::setJoyLikelihood()'
466467
name: setJoyLikelihood
@@ -475,7 +476,7 @@ items:
475476
-
476477
id: var
477478
var_type: int
478-
description: ''
479+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>. '
479480
returns:
480481
-
481482
var_type: $this
@@ -492,6 +493,7 @@ items:
492493
returns:
493494
-
494495
var_type: int
496+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>.'
495497
-
496498
uid: '\Google\Cloud\Vision\V1\FaceAnnotation::setSorrowLikelihood()'
497499
name: setSorrowLikelihood
@@ -506,7 +508,7 @@ items:
506508
-
507509
id: var
508510
var_type: int
509-
description: ''
511+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>. '
510512
returns:
511513
-
512514
var_type: $this
@@ -523,6 +525,7 @@ items:
523525
returns:
524526
-
525527
var_type: int
528+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>.'
526529
-
527530
uid: '\Google\Cloud\Vision\V1\FaceAnnotation::setAngerLikelihood()'
528531
name: setAngerLikelihood
@@ -537,7 +540,7 @@ items:
537540
-
538541
id: var
539542
var_type: int
540-
description: ''
543+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>. '
541544
returns:
542545
-
543546
var_type: $this
@@ -554,6 +557,7 @@ items:
554557
returns:
555558
-
556559
var_type: int
560+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>.'
557561
-
558562
uid: '\Google\Cloud\Vision\V1\FaceAnnotation::setSurpriseLikelihood()'
559563
name: setSurpriseLikelihood
@@ -568,7 +572,7 @@ items:
568572
-
569573
id: var
570574
var_type: int
571-
description: ''
575+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>. '
572576
returns:
573577
-
574578
var_type: $this
@@ -585,6 +589,7 @@ items:
585589
returns:
586590
-
587591
var_type: int
592+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>.'
588593
-
589594
uid: '\Google\Cloud\Vision\V1\FaceAnnotation::setUnderExposedLikelihood()'
590595
name: setUnderExposedLikelihood
@@ -599,7 +604,7 @@ items:
599604
-
600605
id: var
601606
var_type: int
602-
description: ''
607+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>. '
603608
returns:
604609
-
605610
var_type: $this
@@ -616,6 +621,7 @@ items:
616621
returns:
617622
-
618623
var_type: int
624+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>.'
619625
-
620626
uid: '\Google\Cloud\Vision\V1\FaceAnnotation::setBlurredLikelihood()'
621627
name: setBlurredLikelihood
@@ -630,7 +636,7 @@ items:
630636
-
631637
id: var
632638
var_type: int
633-
description: ''
639+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>. '
634640
returns:
635641
-
636642
var_type: $this
@@ -647,6 +653,7 @@ items:
647653
returns:
648654
-
649655
var_type: int
656+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>.'
650657
-
651658
uid: '\Google\Cloud\Vision\V1\FaceAnnotation::setHeadwearLikelihood()'
652659
name: setHeadwearLikelihood
@@ -661,7 +668,7 @@ items:
661668
-
662669
id: var
663670
var_type: int
664-
description: ''
671+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>. '
665672
returns:
666673
-
667674
var_type: $this

‎dev/tests/fixtures/docfx/Vision/V1.Feature.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ items:
6363
returns:
6464
-
6565
var_type: int
66+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Feature\Type">Type</xref>.'
6667
-
6768
uid: '\Google\Cloud\Vision\V1\Feature::setType()'
6869
name: setType
@@ -77,7 +78,7 @@ items:
7778
-
7879
id: var
7980
var_type: int
80-
description: ''
81+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Feature\Type">Type</xref>. '
8182
returns:
8283
-
8384
var_type: $this

‎dev/tests/fixtures/docfx/Vision/V1.OperationMetadata.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@ items:
6565
returns:
6666
-
6767
var_type: int
68+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\OperationMetadata\State">State</xref>.'
6869
-
6970
uid: '\Google\Cloud\Vision\V1\OperationMetadata::setState()'
7071
name: setState
@@ -79,7 +80,7 @@ items:
7980
-
8081
id: var
8182
var_type: int
82-
description: ''
83+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\OperationMetadata\State">State</xref>. '
8384
returns:
8485
-
8586
var_type: $this

‎dev/tests/fixtures/docfx/Vision/V1.SafeSearchAnnotation.yml‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ items:
9090
returns:
9191
-
9292
var_type: int
93+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>.'
9394
-
9495
uid: '\Google\Cloud\Vision\V1\SafeSearchAnnotation::setAdult()'
9596
name: setAdult
@@ -107,7 +108,7 @@ items:
107108
-
108109
id: var
109110
var_type: int
110-
description: ''
111+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>. '
111112
returns:
112113
-
113114
var_type: $this
@@ -127,6 +128,7 @@ items:
127128
returns:
128129
-
129130
var_type: int
131+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>.'
130132
-
131133
uid: '\Google\Cloud\Vision\V1\SafeSearchAnnotation::setSpoof()'
132134
name: setSpoof
@@ -144,7 +146,7 @@ items:
144146
-
145147
id: var
146148
var_type: int
147-
description: ''
149+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>. '
148150
returns:
149151
-
150152
var_type: $this
@@ -161,6 +163,7 @@ items:
161163
returns:
162164
-
163165
var_type: int
166+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>.'
164167
-
165168
uid: '\Google\Cloud\Vision\V1\SafeSearchAnnotation::setMedical()'
166169
name: setMedical
@@ -175,7 +178,7 @@ items:
175178
-
176179
id: var
177180
var_type: int
178-
description: ''
181+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>. '
179182
returns:
180183
-
181184
var_type: $this
@@ -195,6 +198,7 @@ items:
195198
returns:
196199
-
197200
var_type: int
201+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>.'
198202
-
199203
uid: '\Google\Cloud\Vision\V1\SafeSearchAnnotation::setViolence()'
200204
name: setViolence
@@ -212,7 +216,7 @@ items:
212216
-
213217
id: var
214218
var_type: int
215-
description: ''
219+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>. '
216220
returns:
217221
-
218222
var_type: $this
@@ -233,6 +237,7 @@ items:
233237
returns:
234238
-
235239
var_type: int
240+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>.'
236241
-
237242
uid: '\Google\Cloud\Vision\V1\SafeSearchAnnotation::setRacy()'
238243
name: setRacy
@@ -251,7 +256,7 @@ items:
251256
-
252257
id: var
253258
var_type: int
254-
description: ''
259+
description: 'Enum of type <xref uid="\\Google\Cloud\Vision\V1\Likelihood">Likelihood</xref>. '
255260
returns:
256261
-
257262
var_type: $this

0 commit comments

Comments
 (0)