In ServiceApi classes, fix wording of documentation about returning errors vs throwing exceptions.

[garrettjonesgoogle]

Currently, the documentation as copied from the proto includes wording like this:

• "Returns NOT_FOUND if the topic does not exist.
• "If the subscription already exists, returns ALREADY_EXISTS."
• "If the corresponding topic doesn't exist, returns NOT_FOUND."
• "The server may return UNAVAILABLE if there are too many concurrent pull requests pending for the given subscription."

These returns are referring to the service, not the api wrapper, which is confusing. The api wrapper actually throws exceptions in these circumstances. The wording of the documentation on the proto needs to be made more idiom-independent. Additionally, if the markup in the proto could indicate the error cases in a structured way, it would make it a lot easier to generate @throws documentation for the errors. That may be a longer-stretch task, though. Before that point, at least a general @throws clause needs to be added. Additionally, the documentation needs to make clear how to get the exact error that occurred (specifically, getting the status code).

[garrettjonesgoogle]

Comment from @aozarov : I think "generate NOT_FOUND", though maybe better than "return NOT_FOUND", is still not clear. Also, what is NOT_FOUND (which looks like a constant) is not clear and this part from the issue description "Additionally, the documentation needs to make clear how to get the exact error that occurred (specifically, getting the status code)." is not dealt with.