Source documentation very unhelpful in describing return values

[sneakyimp]

I refer to the documentation on AnnotateImageResponse::getTextAnnotations. Your documentation provides only the barest and unhelpful description of the return results:

getTextAnnotations

If present, text (OCR) detection has completed successfully.

Generated from protobuf field repeated .google.cloud.vision.v1.EntityAnnotation
text_annotations = 5;

Returns

Google\Protobuf\Internal\RepeatedField

More Information

Source Code

It looks like one is going to receive an array or some object of the iterable pseudotype, but we have no idea what class these objects might be, what properties/methods they might have, or how we might deal with them in a foreach loop. This documentation really leaves a lot to be desired. An alternative might be better javadoc comments documenting the source itself so our IDE can give us come code hinting.

[dwsupplee]

@sneakyimp This is a really great point. I agree we can do better here. For our handwritten classes we used a syntax akin to generics in order to document the type of class returned from an iterable: https://googleapis.github.io/google-cloud-php/#/docs/google-cloud/v0.116.0/bigquery/dataset?method=tables

Google\Cloud\Core\Iterator\ItemIterator<Google\Cloud\BigQuery\Table>

Would you be on board with us doing something similar in protobuf as well?

[sneakyimp]

@dwsupplee What you suggest sounds helpful. Any additional detail at all would be an improvement. I'd strongly suggest code examples. There's also quite a bit of additional detail you could provide:

• the returned set is an array of EntityAnnotation objects (is this the case??)
• the first (i.e., 0th) annotation contains the entire text scanned from the image, with lines separated by \n characters
• each individual annotation after the first (0th) annotation appears to be a single "word" -- i.e., there is no whitespace in it.

All this sort of information would be extremely useful if it is in fact the case. The spartan information you have now is not really of any use at all.

I would hold up as a beautiful example the PHP documentation at https://php.net -- the kind of detail those docs offers has been instrumental in making PHP as widespread as it is.

[bshaffer]

Good news! We've released new reference documentation for PHP! However, your feature request is still not there (these files are generated by protobuf, so we'll have to add this over there). I've created a PR in the protobuf repo to add support for this: protocolbuffers/protobuf#11734