Use C++ style comments

[sindrehan]

The tool for generating the python API (gapic-generator-python) does not support the C style (/** foo bar */) comments very well so I suggest that we use C++ style comments instead (// foo bar)

[follesoe]

Does it work with the https://github.com/pseudomuto/protoc-gen-doc tool? If not I propose we leave it as is, but rather do a pre-compile step on the Python side to remove or replace the comments, but not check it in. If they do, no problem.

But so strange that they don't support that comment style, given how it is officially supported in the Protobuf language guide, and is such a simple ting to fix..?

https://protobuf.dev/programming-guides/proto3/#adding-comments

[sindrehan]

They do support it to some extent (it compiles), but it confuses the extra asterix with a start of a list so the docstring becomes

class GetTelemetryReq(proto.Message):
    r"""-

    Request to get latest telemetry data

    Attributes:
        message_type (str):
            Message name, f. ex. "AttitudeTel".
    """

    message_type = proto.Field(proto.STRING, number=1)

Instead of

class GetTelemetryReq(proto.Message):
    r"""Request to get latest telemetry data

    Attributes:
        message_type (str):
            Message name, f. ex. "AttitudeTel".
    """

    message_type = proto.Field(proto.STRING, number=1)

If I were to guess, I would say that Google only use // for comments internally, so they haven't bothered to test it properly.

The protoc-gen-doc tool supports both types, so there should be no problem on that front.